Unblock a Pix Refund

Use this endpoint to unblock a refund stuck in PROCESSING or PENDING status. The endpoint fetches the current reversal status from BTG and triggers the appropriate refund settlement flow if BTG shows the reversal has completed or failed; the optional request body field allowNotFoundUnblock (default false) opts into resolving a CASHOUT refund as FAILED when BTG reports the reversal absent (404), or an intra-PSP refund parked at CREATED that Midaz holds no transaction for (nothing reverted). An inter-PSP refund at CREATED is refused with 422 (PIX-0470): its Midaz debit may exist unrecorded, so an operator resolves it. A refund of an intra-PSP transfer, which BTG never holds, is settled on Midaz alone at CREATED, PENDING or PROCESSING, 65 minutes after its last write. A PENDING refund updated less than 150 seconds ago is also refused with 422 (PIX-0470): the create flow may still be sending it to BTG. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored, and an empty body is valid.

POST /v1/refunds/{refund_id}/unblock

Unblock a Pix Refund

cURL

curl --request POST \
  --url https://api.example.com/v1/refunds/{refund_id}/unblock \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/octet-stream' \
  --header 'X-Account-Id: <x-account-id>' \
  --data '<string>'

200

{
  "btgStatus": "CONFIRMED",
  "message": "Refund successfully unblocked.",
  "refund": {
    "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 · requerido

Unique identifier of the Midaz Ledger Account (UUID format)

Parámetros de ruta

refund_id · string · requerido

Refund ID (UUID format)

Cuerpo

application/octet-stream

The body is of type file.

Respuesta

200

application/json

OK

btgStatus · string · requerido

Status retrieved from BTG (for transparency)

Ejemplo:

"CONFIRMED"

message · string · requerido

Additional context about the unblock result

Ejemplo:

"Refund successfully unblocked."

refund · object · requerido

Updated refund details after the unblock attempt

Show child attributes