Pix out

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

POST /v1/consumers/{consumerId}/pix/devolutions

Reverse a Pix, in either direction

Returns money on the Pix rail itself, keyed on the ORIGINAL payment's endToEndId. This is not a charge refund and it does not go through a charge: the rail reverses the transfer, and the consumer's governed wallet is mirrored to match.

WHICH WAY THE MONEY GOES IS payment_direction, AND IT IS EASY TO GET BACKWARDS. It describes the ORIGINAL payment from the consumer's point of view, not the movement you are asking for. inbound (the default) means the consumer RECEIVED that payment, so the devolution sends it back to whoever paid. outbound means the consumer SENT it, so the devolution brings the money BACK to the consumer. Sending the wrong one does not fail loudly — it reverses a real payment in the wrong direction — so set it explicitly rather than leaning on the default.

idempotency_key IS REQUIRED, and it is the only thing standing between a retry and a second reversal. The server mints its own client_code from it for the provider, so the correlation survives even a response you never saw. Reuse the same key for the same intent and a replay comes back as 200 with idempotent_replay: true; a first dispatch is 201. Reusing one key for a DIFFERENT devolution is refused with idempotency_key_conflict rather than silently accepted.

THE AMOUNT IS OPTIONAL IN EXACTLY ONE CASE. When an inbound payment credited a governed wallet, omitting amount_minor returns the remaining reversible amount, computed from the consumer's own statement. Everywhere else — and on every outbound devolution — it is required, and omitting it is amount_required. A partial reversal is allowed; asking for more than was received is devolution_amount_exceeds_received.

TENANCY IS PROVED FROM THE PROVIDER, NOT FROM OUR TABLES. The original payment has to appear on this consumer's own account statement before anything is dispatched, which is why an unknown or foreign end_to_end_id answers devolution_source_not_found rather than a permission error. It also means the call FAILS CLOSED when the statement cannot be read: statement_unavailable with 503, never a dispatch on an unverified reference.

A 502 psp_dispatch_uncertain IS THE ONE THAT NEEDS A HUMAN-SAFE RULE. It means the request may have reached the provider and the answer did not come back — a timeout, a reset, an unparseable body. Money may have moved. The safe move is to re-send the SAME idempotency_key, which either replays the recorded outcome or resolves it; it is never to issue a second devolution with a new key.

SLOW, AND DELIBERATELY SO. A statement read precedes the dispatch, and the dispatch is a real rail call. Allow for it rather than timing out into a retry you did not mean.

Path parameters

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "end_to_end_id": "endtoend_0000000000000000",
       "amount_minor": 1000,
       "idempotency_key": "string",
       "reason": "string",
       "description": "string",
       "payment_direction": "inbound"
     }'

POST /v1/consumers/{consumerId}/pix/devolutions HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "end_to_end_id": "endtoend_0000000000000000",
  "amount_minor": 1000,
  "idempotency_key": "string",
  "reason": "string",
  "description": "string",
  "payment_direction": "inbound"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "end_to_end_id": "endtoend_0000000000000000",
      "amount_minor": 1000,
      "idempotency_key": "string",
      "reason": "string",
      "description": "string",
      "payment_direction": "inbound"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "end_to_end_id": "endtoend_0000000000000000",
    "amount_minor": 1000,
    "idempotency_key": "string",
    "reason": "string",
    "description": "string",
    "payment_direction": "inbound"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/consumers/{consumerId}/pix/devolutions", {
  path: {
    consumerId: "csm_0000000000000000"
  },
  body: {
    end_to_end_id: "endtoend_0000000000000000",
    amount_minor: 1000,
    idempotency_key: "string",
    reason: "string",
    description: "string",
    payment_direction: "inbound"
  }
});
// r.status is one of the documented statuses (200, 422),
// each with its own body shape in r.data; nothing here throws on 422.
if (r.ok) {
  console.log(r.data);
}

{
  "devolution_id": "devolution_0000000000000000",
  "status": "pending",
  "payment_direction": "inbound",
  "end_to_end_id": "endtoend_0000000000000000",
  "amount_minor": 1000,
  "currency": "BRL",
  "reason": "string",
  "client_code": "string",
  "return_identification": "string",
  "original_payment_id": "originalpayment_0000000000000000",
  "wallet_id": "wlt_0000000000000000",
  "charge_id": "charge_0000000000000000",
  "failure_reason": "string",
  "created_at": "2026-01-15T12:00:00.000Z",
  "settled_at": "2026-01-15T12:00:00.000Z",
  "idempotent_replay": true,
  "status_message": "string"
}

GET /v1/consumers/{consumerId}/pix/devolutions/{devolutionId}

A Pix devolution's state

The recorded devolution, with settlement resolved from the consumer's own account statement when the recorded state is not yet terminal.

The statement is the only provider truth available here: the provider's status poll never resolves reversals, so reading the reversal movement on the consumer's own statement is what settles the row. A statement fetch that fails degrades to provider_truth: "unavailable" and returns the recorded state, never an error: the row itself is always answerable.

A devolution belonging to another organization, project or consumer answers the same 404 an unknown id does.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions/{devolutionId} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/consumers/{consumerId}/pix/devolutions/{devolutionId} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions/{devolutionId}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix/devolutions/{devolutionId}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/consumers/{consumerId}/pix/devolutions/{devolutionId}", {
  path: {
    consumerId: "csm_0000000000000000",
    devolutionId: "devolution_0000000000000000"
  }
});

{
  "devolution_id": "devolution_0000000000000000",
  "status": "pending",
  "payment_direction": "inbound",
  "end_to_end_id": "endtoend_0000000000000000",
  "amount_minor": 1000,
  "currency": "BRL",
  "reason": "string",
  "client_code": "string",
  "return_identification": "string",
  "original_payment_id": "originalpayment_0000000000000000",
  "wallet_id": "wlt_0000000000000000",
  "charge_id": "charge_0000000000000000",
  "failure_reason": "string",
  "created_at": "2026-01-15T12:00:00.000Z",
  "settled_at": "2026-01-15T12:00:00.000Z",
  "idempotent_replay": true,
  "status_message": "string",
  "provider_truth": "statement"
}