Process a Pix Transfer

Process a previously initiated Pix cash-out and move funds between accounts. A cash-out whose Midaz debit outcome is unknown is still answered 201, at status CREATED, and keeps its initiation; its outcome arrives later by the transfer webhook. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored. The optional body field contestedMedRootTransactionId is the rootTransactionId of the funds recovery contested in the MED. It is required when X-Purpose is INSTANT_PAYMENT_REFUND and the destination is another PSP: after trimming, it must be exactly 32 ASCII letters, digits or underscores, and the trimmed value is sent to BTG. Such a refund is rejected before any Midaz debit with 400 PIX-0481 when the field is missing and 400 PIX-0482 when it is malformed. BTG receives it as a MANUAL payment to the destination account resolved at initiation, without the Pix key. An intra-PSP refund, which never reaches BTG, and the TRANSFER, WITHDRAWAL and CHANGE purposes ignore the field.

POST /v1/transfers/cashout/process

Process a Pix Transfer

cURL

curl --request POST \
  --url https://api.example.com/v1/transfers/cashout/process \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/octet-stream' \
  --data '<string>'

201

{
  "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

Account ID (UUID format)

X-Purpose · string

Transaction purpose (TRANSFER, INSTANT_PAYMENT_REFUND, WITHDRAWAL for a Pix Saque charge, CHANGE for a Pix Troco charge). Defaults to TRANSFER. An INSTANT_PAYMENT_REFUND to another PSP requires the body field contestedMedRootTransactionId (400 PIX-0481 when missing, 400 PIX-0482 when malformed). An intra-PSP refund and every other purpose ignore the field.

Cuerpo

application/octet-stream

The body is of type file.

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:15Z"

endToEndId · string · requerido

Ejemplo:

"E1234567820240101000001234567890"

id · string · requerido

Ejemplo:

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

initiationType · enum<string> · requerido

Opciones disponibles: MANUAL, KEY, QR_CODE

Ejemplo:

"KEY"

paymentType · enum<string> · requerido

Opciones disponibles: IMMEDIATE, SCHEDULED

Ejemplo:

"IMMEDIATE"

purpose · enum<string> · requerido

Opciones disponibles: TRANSFER, INSTANT_PAYMENT_REFUND, CHANGE, WITHDRAWAL

Ejemplo:

"TRANSFER"

status · enum<string> · requerido

Opciones disponibles: CREATED, PENDING, PROCESSING, COMPLETED, FAILED, REVERSED

Ejemplo:

"COMPLETED"

type · enum<string> · requerido

Opciones disponibles: CASHIN, CASHOUT

Ejemplo:

"CASHIN"

updatedAt · string · requerido

Ejemplo:

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

urgency · enum<string> · requerido

Opciones disponibles: HIGH, NORMAL

Ejemplo:

"HIGH"

aliasId · string

Ejemplo:

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

deletedAt · string

description · string

Ejemplo:

"Pix Cashin Transfer"

destination · object

Show child attributes

feeCharge · object

Show child attributes

initiatedAt · string

Ejemplo:

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

ledger · object

Show child attributes

metadata · object

Show child attributes

source · object

Show child attributes

txId · string

Transaction ID (txId) declared by the QR Code this cash-in paid. For a dynamic QR Code it is the charge's own txId, proven against that charge before the cash-in was accepted. For a static BR Code it is whatever reference label the code declared, which may match no charge. initiationType answers QR_CODE for both, so treat this as a correlation hint rather than proof a charge was paid. Absent for a payment with no QR Code and for every cash-out.

Ejemplo:

"cob7f3a9c2e4b118d"

withdrawal · object

Show child attributes