Unblock a Pix Transfer

Use this endpoint to unblock a transaction that is stuck in PENDING or PROCESSING status. The endpoint fetches the current status from BTG and triggers the appropriate settlement flow if BTG shows the transaction has completed or failed. The optional request body field allowNotFoundUnblock (default false) gates ONLY the not-found branches: a BTG 404, which reverts a cash-out’s Midaz debit and fails it, and an intra-PSP cash-out parked at CREATED that Midaz holds no transaction for, which fails with nothing reverted; a cash-out whose status changed while BTG was queried is refused with 422 (PIX-0470) and nothing is reverted. An inter-PSP cash-out at CREATED is refused with 422 (PIX-0470): its Midaz debit may exist unrecorded, so an operator resolves it. An intra-PSP cash-out, which BTG never holds, is settled on Midaz alone: at CREATED 65 minutes after its creation, at PENDING 65 minutes after its last write. A cash-out at PENDING updated less than 150 seconds ago is also refused with 422 (PIX-0470): the cash-out flow may still be sending it to BTG. A repeat on a terminal cash-out closes a schedule it left PROCESSING and re-sends the recurring module’s terminal event and a reverted rejection’s client webhook, then answers 422; a 500 after the terminal write means one of these failed: repeat the call, which never reverts again. 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/transfers/{transfer_id}/unblock

Unblock a Pix Transfer

cURL

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

200

{
  "btgStatus": "<string>",
  "message": "<string>",
  "transfer": {
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "amount": "100.50",
    "createdAt": "2024-01-15T10:30:15Z",
    "endToEndId": "E1234567820240101000001234567890",
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "initiationType": "KEY",
    "paymentType": "IMMEDIATE",
    "purpose": "TRANSFER",
    "status": "COMPLETED",
    "type": "CASHIN",
    "updatedAt": "2024-01-15T10:35:00Z",
    "urgency": "HIGH",
    "aliasId": "01989f9e-6508-79f8-9540-835be49fbd0e",
    "deletedAt": "<string>",
    "description": "Pix Cashin Transfer",
    "destination": {
      "account": {
        "branch": "0001",
        "number": "123456789",
        "participant": "12345678",
        "type": "TRAN"
      },
      "key": "[e-mail]",
      "owner": {
        "document": "12ABC34501DE35",
        "name": "John Doe",
        "type": "NATURAL_PERSON",
        "tradeName": "John's Business"
      }
    },
    "feeCharge": {
      "applied": true,
      "calculationType": "segment",
      "fees": [
        {
          "amount": "1.50",
          "calculationType": "PERCENTAGE",
          "calculationValue": "1.5",
          "creditAccount": "01989f9e-6508-79f8-9540-835be49fbd0d",
          "feeLabel": "PIX_FEE"
        }
      ],
      "netAmount": "97.50",
      "totalAmount": "2.50"
    },
    "initiatedAt": "2024-01-15T10:30:00Z",
    "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": {},
    "source": {
      "account": {
        "branch": "0001",
        "number": "123456789",
        "participant": "12345678",
        "type": "TRAN"
      },
      "key": "[e-mail]",
      "owner": {
        "document": "12ABC34501DE35",
        "name": "John Doe",
        "type": "NATURAL_PERSON",
        "tradeName": "John's Business"
      }
    },
    "txId": "cob7f3a9c2e4b118d",
    "withdrawal": {
      "agentMode": "AGTEC",
      "withdrawalAmount": "50.00",
      "withdrawalServiceProvider": "12345678",
      "transactionAmount": "80.00"
    }
  }
}

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

transfer_id · string · requerido

Transfer ID (UUID format)

Cuerpo

application/octet-stream

The body is of type file.

Respuesta

200

application/json

OK

btgStatus · string · requerido

message · string · requerido

transfer · object · requerido

Show child attributes