Create an outbound Pix refund (MED)

Issues a refund against a previously completed CASHIN transfer with a structured pacs.004 reasonCode. A refund the rail refuses answers 422 PIX-0013 and its debit is reverted; if that revert does not complete, the refund stays PROCESSING. A provider send that fails without proving the pacs.004 was not sent (a timeout, a 5xx) compensates nothing and answers 201 with status PROCESSING, as a refund the provider accepts without a provider reference does: the debit stays recorded until the outcome arrives by end-to-end id (GET the refund or wait for its callback). A retry with the same X-Idempotency key replays the original 201 response, with X-Idempotency-Replayed: true, instead of creating a second refund, including when the request timed out while the provider was answering. After a 5xx or a 409 PIX-0406, the same key answers the refund that the first attempt created, in its current state, with 201 and without X-Idempotency-Replayed, as long as that refund is not FAILED: the refund can still be PROCESSING with its debit, so read it with GET to see its outcome. A resend that keeps answering 412 PIX-0031 with Retry-After: 1 is still in flight. The same key with a different transfer, amount, reasonCode or reason answers 412 PIX-0031. Once the refund is FAILED and no replay record is left, the key is free and a retry under it creates a new refund.

POST /transfers/{id}/refunds

Create an outbound Pix refund (MED)

cURL

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/{id}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "100.00",
  "reason": "Estorno solicitado pelo pagador",
  "reasonCode": "MD06"
}
'

201

{
  "amount": "100.00",
  "createdAt": "2026-05-06T10:45:00Z",
  "id": "019606b1-3b4c-7d8e-9f01-234567890dee",
  "originalEndToEndId": "E12345678202605061030abcdef12345",
  "reasonCode": "MD06",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:45:30Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Estorno solicitado pelo pagador",
  "ledger": {
    "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
    "revert": {
      "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
      "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
      "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
    },
    "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
    "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
  },
  "metadata": {},
  "returnEndToEndId": "D12345678202605061045fedcba54321",
  "feeCharge": {
    "applied": true,
    "calculationType": "LEDGER",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "LEDGER_FEE",
        "calculationType": "LEDGER",
        "calculationValue": "<string>",
        "creditAccount": "@fees-pix"
      }
    ],
    "netAmount": "100.00",
    "totalAmount": "1.50"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Account-Id · string · requerido

Account UUID

Ejemplo:

"019606a1-3b4c-7d8e-9f01-234567890abc"

Parámetros de ruta

id · string · requerido

Original transfer UUID

Ejemplo:

"0196070b-1234-7890-abcd-ef0123456789"

Cuerpo

application/json

amount · string · requerido

Refund amount

Ejemplo:

"100.00"

reason · string · requerido

Human-readable refund reason, sent in the pacs.004. U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003).

Ejemplo:

"Estorno solicitado pelo pagador"

reasonCode · enum<string> · requerido

pacs.004 RtrRsnInf reason code

Opciones disponibles: MD06, SL02, FR01, BE08

Ejemplo:

"MD06"

Respuesta

201

application/json

Created

amount · string · requerido

Ejemplo:

"100.00"

createdAt · string<date-time> · requerido

Ejemplo:

"2026-05-06T10:45:00Z"

id · string · requerido

Ejemplo:

"019606b1-3b4c-7d8e-9f01-234567890dee"

originalEndToEndId · string · requerido

Ejemplo:

"E12345678202605061030abcdef12345"

reasonCode · string · requerido

Ejemplo:

"MD06"

status · string · requerido

Ejemplo:

"COMPLETED"

type · string · requerido

Ejemplo:

"OUTBOUND"

updatedAt · string<date-time> · requerido

Ejemplo:

"2026-05-06T10:45:30Z"

accountId · string

Ejemplo:

"019606a0-1a2b-7c3d-8e4f-567890123abc"

deletedAt · string<date-time>

description · string

Ejemplo:

"Estorno solicitado pelo pagador"

ledger · object

Show child attributes

metadata · object

Show child attributes

returnEndToEndId · string

Ejemplo:

"D12345678202605061045fedcba54321"

feeCharge · object

Fee the ledger reported on the create that moved the refund's money. Absent when no fee answer was recorded for this refund (its ledger create never landed, an error was logged at the time, or the refund was created before fees were read back); {"applied": false} when the ledger reported that no fee was charged; the full object when it charged one. A refund carries no ledger.revert field and needs none here: a FAILED refund that carries feeCharge was reverted first -- every path that writes a refund FAILED after its ledger create landed reverts the debit before marking it (a revert that does not complete leaves the refund PROCESSING), and every other path fails before any create -- so the fee was returned with the amount; applied reports what the create did and the object records the create.

Show child attributes