Refund a Received Pix Transfer

Use this endpoint to initiate a refund for a previously received Pix transfer. Optionally provide an operations array for distributed partial refunds from multiple accounts. Only received Pix transfers (cash-in) can be refunded; the sum of all refunds cannot exceed the original amount. A create carries X-Idempotency or X-Return-End-To-End; one with neither is refused 400 PIX-0001 and moves no money, and a resend with either anchor returns the first refund. A refund whose Midaz debit outcome is unknown is still answered 201, at status CREATED, and stays reserved against the original amount; its outcome arrives later by the refund webhook.

POST /v1/transfers/{transfer_id}/refunds

Refund a Received Pix Transfer

cURL

curl --request POST \
  --url https://api.example.com/v1/transfers/{transfer_id}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Reason: <x-reason>' \
  --data '
{
  "amount": "100.50",
  "description": "Customer reported unauthorized transaction",
  "metadata": {},
  "operations": [
    {
      "accountAlias": "@account/alias-conta-cliente",
      "amount": "100.50"
    }
  ]
}
'

201

{
  "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
  "amount": "100.50",
  "createdAt": "2024-01-15T10:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "originalEndToEndId": "E12345678202411241430ABCDEFGHIJK",
  "returnEndToEndId": "D3030629420200808185300887639654",
  "status": "PENDING",
  "type": "CASHOUT",
  "updatedAt": "2024-01-15T10:30:00Z",
  "deletedAt": "<string>",
  "description": "Customer reported unauthorized transaction",
  "ledger": {
    "destinationOperationId": "550e8400-e29b-41d4-a716-446655440013",
    "revert": {
      "destinationOperationId": "550e8400-e29b-41d4-a716-446655440016",
      "sourceOperationId": "550e8400-e29b-41d4-a716-446655440015",
      "transactionId": "550e8400-e29b-41d4-a716-446655440014"
    },
    "sourceOperationId": "550e8400-e29b-41d4-a716-446655440012",
    "transactionId": "550e8400-e29b-41d4-a716-446655440011"
  },
  "metadata": {}
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Account-Id · string<uuid> · requerido

Account ID that received the original transfer (UUID format)

X-Reason · enum<string> · requerido

Refund reason code

Opciones disponibles: BE08, FR01, MD06, SL02

X-Return-End-To-End · string

Custom return end-to-end ID (32 chars, D prefix); required unless X-Idempotency is sent

X-Idempotency · string

Idempotency key of the create; required unless X-Return-End-To-End is sent

Parámetros de ruta

transfer_id · string<uuid> · requerido

Database UUID of the original Pix transfer (cashin)

Cuerpo

application/json

amount · string · requerido

Minimum string length: 1

Ejemplo:

"100.50"

description · string

Maximum string length: 140

Ejemplo:

"Customer reported unauthorized transaction"

metadata · object

Show child attributes

operations · object[]

Required array length: 1 - 50 elements

Show child attributes

Respuesta

201

application/json

Created

accountId · string · requerido

Ejemplo:

"01989f9e-6508-79f8-9540-835be49fbd0d"

amount · string · requerido

Ejemplo:

"100.50"

createdAt · string · requerido

Ejemplo:

"2024-01-15T10:30:00Z"

id · string · requerido

Ejemplo:

"550e8400-e29b-41d4-a716-446655440001"

originalEndToEndId · string · requerido

Ejemplo:

"E12345678202411241430ABCDEFGHIJK"

returnEndToEndId · string · requerido

Ejemplo:

"D3030629420200808185300887639654"

status · enum<string> · requerido

Opciones disponibles: CREATED, PENDING, PROCESSING, COMPLETED, REJECTED, FAILED, CANCELLED

Ejemplo:

"PENDING"

type · enum<string> · requerido

Opciones disponibles: CASHOUT, CASHIN

Ejemplo:

"CASHOUT"

updatedAt · string · requerido

Ejemplo:

"2024-01-15T10:30:00Z"

deletedAt · string

description · string

Ejemplo:

"Customer reported unauthorized transaction"

ledger · object

Show child attributes

metadata · object

Show child attributes