Create a PIX refund

Creates a PIX refund (devolução) against an executed transaction. Bacen makes the refund the RECIPIENT’s operation, so the caller must be the party that RECEIVED the original payment: the requesting accountId’s document has to equal the original payee’s document. The original payer cannot refund a payment it sent — that is the MED/fraud path, not this one.

Identify the original with BOTH transactionId (the local UUID) and endToEndId, and it must still be EXECUTED. Partial refunds are allowed and they ACCUMULATE: the amount is checked against the original amount minus everything already refunded, under a row lock on the original, so two concurrent refunds cannot together exceed it. An on-us original is refunded as a synchronous ledger reversal from the refunder to the original payer; a payment received from another institution is submitted to JDPI first, and the refund’s own end-to-end id comes back from JD. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02.

⚠️ Send clientRequestId on an on-us refund. Without it a retry posts a SECOND reversal: each attempt mints a fresh refund end-to-end id, so nothing dedups them, and the money moves twice. With it, a retry replays the existing refund as a success. The cross-institution branch is already retry-safe on its own.

Refusals: 422 PIX-0036 when no EXECUTED transaction matches that (endToEndId, transactionId) pair; 400 PIX-0089 when the original is an outgoing payment (only the receiving institution can return what it received); 400 PIX-0087 when the caller is refunding its own outgoing payment; 400 PIX-0088 when the caller is not the original payee; 409 PIX-0032 when this amount plus the prior refunds would exceed the original; 422 PIX-0030 on a non-positive amount; 422 PIX-0108 when the requesting account is not bound to a ledger account; 400 PIX-0061 when accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values.

POST /v1/refunds

Create a PIX refund

cURL

curl --request POST \
  --url https://api.example.com/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "transactionId": "d1f9c0a2-...",
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Wrong amount"
}
'

201

{
  "accountId": "ext-acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "endToEndRefundId": "D1234567890",
  "id": "a2f9c0d1-...",
  "status": "EXECUTED",
  "description": "Wrong amount"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

accountId · string · required

The requesting account (the original payee).

Example:

"acc-123"

amount · integer<int64> · required

Refund amount in centavos (must be greater than zero).

Example:

5000

code · string · required

PIX return reason (BE08/FR01/MD06/SL02).

Example:

"MD06"

endToEndId · string · required

The original transaction's end-to-end id.

Example:

"E1234567890"

transactionId · string · required

The original transaction id (UUID).

Example:

"d1f9c0a2-..."

clientRequestId · string

Optional client idempotency token. A retry carrying the same value replays the existing refund instead of creating a duplicate (intra-PSP double-refund protection); omit to opt out.

Example:

"req-2025-01-01-abc123"

description · string

Free-text refund description.

Example:

"Wrong amount"

Response

201

application/json

Created

accountId · string · required

The refunding account id.

Example:

"ext-acc-123"

amount · integer<int64> · required

Refund amount in centavos.

Example:

5000

code · string · required

The PIX return reason.

Example:

"MD06"

endToEndId · string · required

The original transaction's end-to-end id.

Example:

"E1234567890"

endToEndRefundId · string · required

The refund's own end-to-end id.

Example:

"D1234567890"

id · string · required

The created refund id.

Example:

"a2f9c0d1-..."

status · string · required

eTransactionStatus name.

Example:

"EXECUTED"

description · string

Refund description.

Example:

"Wrong amount"