Payouts

A payout sends money in local currency to a bank account in the destination country. The amount converts from local currency to USDT at your account’s rate (the one from GET /v1/rates) and usdt_amount + fee (the fixed fee, when configured) is debited from your balance. This is the full lifecycle, including what happens to your balance at each step:

1. Discover the available corridors

Countries, currencies and methods are defined by CBPay. Always check the catalog:

curl https://api.qbank.cl/platform/v1/payouts/methods \
  -H "Authorization: Bearer <token>"

{
  "items": [
    { "country": "CL", "currency": "CLP", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "yape" },
    { "country": "BO", "currency": "BOB", "method": "qr" }
  ],
  "meta": { "retrieved": 4 }
}

Available corridors and methods:

Country	Currency	Methods
Chile	CLP	`bank_transfer`
Peru	PEN	`bank_transfer`, `yape`
Mexico	MXN	`bank_transfer` (SPEI: CLABE or debit card)
Venezuela	VES	`bank_transfer`, `pago_movil`
Bolivia	BOB / USD	`bank_transfer`, `qr` (see QR payout)
Brazil	BRL	`pix` (by key or to account), `qr` (PIX QR — see QR payout)
Ecuador	USD	`bank_transfer`, `deuna`, `cash_pickup`, `cnb`
Paraguay	PYG	`bank_transfer`

Availability may vary; the catalog (GET /v1/payouts/methods) is always the source of truth. If a country has a single method, method is optional. Every method is charged the same way: your rate + fixed fee. For bank transfers you also need the banks catalog (that is where the beneficiary’s bank_code comes from):

curl "https://api.qbank.cl/platform/v1/payouts/banks?country=CL" \
  -H "Authorization: Bearer <token>"

{
  "items": [
    { "code": "001", "name": "Banco de Chile" },
    { "code": "012", "name": "Banco del Estado de Chile" },
    { "code": "016", "name": "Banco de Crédito e Inversiones" }
  ],
  "meta": { "retrieved": 3 }
}

2. Create the payout

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "1500.00",
    "beneficiary": {
      "name": "Maria Lopez",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "description": "Invoice 8841",
    "idempotency_key": "invoice-8841"
  }'

beneficiary is a key/value object whose required fields depend on the corridor (RUT and bank in Chile, CLABE in Mexico, CCI in Peru, PIX key in Brazil, etc.). The methods catalog documents each one.

Every payout saves the beneficiary as a contact automatically ("save_contact": false to skip it). To pay them again without re-typing their data, send "beneficiary_contact_id" instead of beneficiary — their most recent saved beneficiary for that country and method is used (422 no_saved_destination if there is none).

Response 202 Accepted:

{
  "payout_id": "0d4f…",
  "account_id": "…",
  "idempotency_key": "invoice-8841",
  "country": "MX",
  "currency": "MXN",
  "method": "bank_transfer",
  "local_amount": "1500.00",
  "fx_rate": "17.50",
  "usdt_amount": "85.714286",
  "fee": "0.300000",
  "total_debit": "86.014286",
  "settlement_asset": "USDT",
  "settlement_amount": "86.014286",
  "settlement_rate": "1",
  "status": "processing",
  "created_at": "2026-07-06T20:00:00Z"
}

At that moment your balance already reflects the debit: total_debit moved from available into held (on the settlement_asset balance).

Paying from another balance (`settlement_asset`)

By default the debit comes from your default settlement asset (USDT unless you change it via PUT /v1/settlement). To pay a single operation from another balance, add settlement_asset to the request. Example: a 100,000 CLP payout paid from the BTC balance goes through four transformations, all recorded on the response:

CLP → USDT at your rate: 100000 / 950.25 = 105.235465 USDT.
+ fixed fee: 105.235465 + 0.30 = 105.535465 USDT (total_debit).
USDT → BTC at the effective settlement price (settlement_rate 109029.34070000): 105.535465 / 109029.3407 = 0.00096795 BTC (rounded up to the satoshi).
Debit and hold in BTC: settlement_amount 0.00096795 leaves your BTC balance; the beneficiary receives their 100,000 CLP exactly as always.

{
  "country": "CL",
  "currency": "CLP",
  "local_amount": "100000",
  "fx_rate": "950.25",
  "usdt_amount": "105.235465",
  "fee": "0.300000",
  "total_debit": "105.535465",
  "settlement_asset": "BTC",
  "settlement_amount": "0.00096795",
  "settlement_rate": "109029.34070000",
  "status": "processing"
}

If the payout fails, the exact settlement_amount is refunded to your BTC balance — never re-quoted. If the BTC/GOLD execution price is unavailable at that moment you get 503 pricing_unavailable, and volatile assets have a per-operation limit (422 settlement_limit_exceeded; check it in GET /v1/settlement).

3. Receive the final state

Subscribe to the payout_status_changed event (webhooks):

{
  "payout_id": "0d4f…",
  "account_id": "…",
  "country": "MX",
  "currency": "MXN",
  "local_amount": "1500.00",
  "usdt_amount": "85.714286",
  "total_debit": "86.014286",
  "status": "completed",
  "status_code": ""
}

completed: the money arrived; the hold is consumed.
failed: the full debit is refunded automatically (payout_refund in your ledger).

You can also query at any time:

curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

Payout statuses

Status	Meaning	Your balance
`processing`	Accepted and executing on the local rail	Debit held in `held`
`completed`	The money reached the beneficiary	Hold consumed — final
`failed`	The corridor rejected it or it failed	Full automatic refund (amount + fee)

Reads and history

Every payout can be read individually and the listing accepts filters:

# One payout
curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

# History with filters: dates, status, country and pagination
curl "https://api.qbank.cl/platform/v1/payouts?from=2026-07-01&to=2026-07-08&status=failed&country=MX&page=1&page_size=50" \
  -H "Authorization: Bearer <token>"

{
  "page": 1,
  "page_size": 50,
  "payouts": [
    {
      "payout_id": "0d4f…",
      "country": "MX",
      "currency": "MXN",
      "method": "bank_transfer",
      "local_amount": "1500.00",
      "fx_rate": "17.50",
      "usdt_amount": "85.714286",
      "fee": "0.300000",
      "total_debit": "86.014286",
      "status": "failed",
      "status_code": "core_rejected",
      "status_message": "beneficiary account does not exist",
      "created_at": "2026-07-06T20:00:00Z"
    }
  ]
}

from/to use YYYY-MM-DD (UTC, both inclusive); an invalid date responds 400 invalid_range.

Examples by country

Every corridor with its exact beneficiary, the full request and the real response. Rates (fx_rate) are illustrative — your account’s rates from GET /v1/rates always apply; the debit is usdt_amount + fee (fixed, when configured; 0.30 here).

Beneficiary fields per corridor

Country	Method	`beneficiary` fields
CL	`bank_transfer`	`name`, `tax_id` (RUT), `bank_code`, `account_type`, `account_number`
PE	`bank_transfer`	`name`, `account_number` (20-digit CCI)
PE	`yape`	`name`, `phone` (`51XXXXXXXXX`)
MX	`bank_transfer`	`name`, `account_type` (`clabe`/`debit_card`), `account_number` (+ `bank_code` for cards)
VE	`pago_movil`	`phone`, `bank_code` (SUDEBAN), `document_value`
VE	`bank_transfer`	`name`, `account_number` (20 digits), `document_value`
BO	`bank_transfer`	`name`, `tax_id`, `bank_code`, `account_number`
BR	`pix`	`name`, `tax_id` + (`pix_key` and `pix_key_type`) or (`bank_code` ISPB, `branch_code`, `account_number`)
EC	`bank_transfer`	`name`, `document_value` (cédula), `sender_name`, `account_number` (+ `bank_code` and `account_type` for other banks)
EC	`deuna`	`name`, `document_value`, `sender_name`, `phone` (wallet mobile number)
EC	`cash_pickup` / `cnb`	`name`, `document_value`, `sender_name` — the beneficiary withdraws with their ID
PY	`bank_transfer`	`name` (max 35 chars), `tax_id`, `bank_code`, `account_number`

Bank transfer in CLP. Requires RUT, bank and account:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CL",
    "currency": "CLP",
    "method": "bank_transfer",
    "amount": "100000",
    "beneficiary": {
      "name": "Pedro Soto Fuentes",
      "tax_id": "12.345.678-5",
      "bank_code": "012",
      "account_type": "checking",
      "account_number": "123456789"
    },
    "description": "Supplier payment",
    "idempotency_key": "cl-prov-0091"
  }'

{
  "payout_id": "b3e1…",
  "country": "CL",
  "currency": "CLP",
  "method": "bank_transfer",
  "local_amount": "100000",
  "fx_rate": "925.69",
  "usdt_amount": "108.027528",
  "fee": "0.300000",
  "total_debit": "108.327528",
  "status": "processing"
}

The banks catalog (GET /v1/payouts/banks?country=CL) lists the current bank_code values.

Two methods: bank transfer (interbank CCI) and Yape (to a phone number).

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PE",
    "currency": "PEN",
    "method": "bank_transfer",
    "amount": "1000.00",
    "beneficiary": {
      "name": "Rosa Alvarez Diaz",
      "account_number": "00219300123456789012"
    },
    "idempotency_key": "pe-cci-3310"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PE",
    "currency": "PEN",
    "method": "yape",
    "amount": "150.00",
    "beneficiary": {
      "name": "Luis Ramos Vega",
      "phone": "51987654321"
    },
    "idempotency_key": "pe-yape-8874"
  }'

{
  "payout_id": "c7a2…",
  "country": "PE",
  "currency": "PEN",
  "method": "yape",
  "local_amount": "150.00",
  "fx_rate": "3.40",
  "usdt_amount": "44.117648",
  "fee": "0.300000",
  "total_debit": "44.417648",
  "status": "completed"
}

For yape the phone uses the 51XXXXXXXXX format (11 digits with country code). The result is usually synchronous.

SPEI in MXN, to a CLABE (18 digits) or a debit card:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "1500.00",
    "beneficiary": {
      "name": "Maria Lopez",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "idempotency_key": "mx-clabe-8841"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "800.00",
    "beneficiary": {
      "name": "Jorge Herrera",
      "account_type": "debit_card",
      "account_number": "4152313412341234",
      "bank_code": "40012"
    },
    "idempotency_key": "mx-card-1102"
  }'

{
  "payout_id": "0d4f…",
  "country": "MX",
  "currency": "MXN",
  "method": "bank_transfer",
  "local_amount": "1500.00",
  "fx_rate": "17.50",
  "usdt_amount": "85.714286",
  "fee": "0.300000",
  "total_debit": "86.014286",
  "status": "processing"
}

With a CLABE the destination bank derives from its leading digits; with a card, bank_code is required.

Two methods: Pago Móvil (phone + bank + ID) and bank transfer (20-digit account):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "VE",
    "currency": "VES",
    "method": "pago_movil",
    "amount": "2000.00",
    "beneficiary": {
      "phone": "04141234567",
      "bank_code": "0102",
      "document_value": "V12345678"
    },
    "idempotency_key": "ve-pm-5567"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "VE",
    "currency": "VES",
    "method": "bank_transfer",
    "amount": "5000.00",
    "beneficiary": {
      "name": "Carmen Delgado",
      "account_number": "01020123456789012345",
      "document_value": "V87654321"
    },
    "idempotency_key": "ve-bank-7810"
  }'

{
  "payout_id": "e9b4…",
  "country": "VE",
  "currency": "VES",
  "method": "pago_movil",
  "local_amount": "2000.00",
  "fx_rate": "666.00",
  "usdt_amount": "3.003004",
  "fee": "0.300000",
  "total_debit": "3.303004",
  "status": "completed"
}

bank_code uses SUDEBAN codes; for bank_transfer it can derive from the account’s first 4 digits.

ACH transfer in BOB or USD (besides the QR):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BO",
    "currency": "BOB",
    "method": "bank_transfer",
    "amount": "1382.00",
    "beneficiary": {
      "name": "Juan Quispe Mamani",
      "tax_id": "4567890",
      "bank_code": "1016",
      "account_number": "1234567890"
    },
    "idempotency_key": "bo-ach-2204"
  }'

{
  "payout_id": "f2c8…",
  "country": "BO",
  "currency": "BOB",
  "method": "bank_transfer",
  "local_amount": "1382.00",
  "fx_rate": "6.91",
  "usdt_amount": "200.000000",
  "fee": "0.300000",
  "total_debit": "200.300000",
  "status": "processing"
}

For USD send currency: "USD" with the same structure.

PIX by key (besides the PIX QR):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "method": "pix",
    "amount": "350.00",
    "beneficiary": {
      "name": "João da Silva",
      "tax_id": "123.456.789-09",
      "pix_key_type": "cpf",
      "pix_key": "12345678909"
    },
    "idempotency_key": "br-pix-3321"
  }'

{
  "payout_id": "a6d1…",
  "country": "BR",
  "currency": "BRL",
  "method": "pix",
  "local_amount": "350.00",
  "fx_rate": "5.13",
  "usdt_amount": "68.226121",
  "fee": "0.300000",
  "total_debit": "68.526121",
  "status": "processing"
}

pix_key_type: cpf, cnpj, phone, email or evp (random key).PIX to account (no key) — when the beneficiary does not have (or share) a PIX key, send their bank details; it arrives just as fast (same PIX rail, 24/7):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "method": "pix",
    "amount": "350.00",
    "beneficiary": {
      "name": "Empresa Exemplo Ltda",
      "tax_id": "19.385.062/0001-20",
      "bank_code": "45678923",
      "branch_code": "1",
      "account_number": "765432",
      "account_type": "CACC"
    },
    "idempotency_key": "br-pix-acct-3322"
  }'

bank_code is the destination bank’s ISPB (8 digits), branch_code the agency, and account_type the account type (CACC checking — default —, SVGS savings, TRAN payment account, SLRY salary).
The final status arrives through the payout_status_changed webhook (continuous reconciliation against the rail); check on demand with GET /v1/payouts/{id}.

Remittances in USD (1 to 10,000 per operation, up to 2 decimals) with four methods: bank transfer, the DE UNA wallet (by mobile number), cash pickup at a branch (cash_pickup) and cash at a non-bank correspondent (cnb). This is a remittance corridor: besides the beneficiary, the rail requires the sender’s data (who originates the payment), sent flat inside the same beneficiary object with the sender_* prefix.

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "EC",
    "currency": "USD",
    "method": "bank_transfer",
    "amount": "250.00",
    "beneficiary": {
      "name": "Carlos Andrade Vera",
      "document_value": "1712345678",
      "account_number": "2203456789",
      "sender_name": "Ana Torres Silva",
      "sender_document_value": "V23456789",
      "sender_country": "US"
    },
    "idempotency_key": "ec-bank-4471"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "EC",
    "currency": "USD",
    "method": "deuna",
    "amount": "80.00",
    "beneficiary": {
      "name": "Lucia Paredes Mora",
      "document_value": "0923456781",
      "phone": "0998765432",
      "sender_name": "Ana Torres Silva"
    },
    "idempotency_key": "ec-deuna-5520"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "EC",
    "currency": "USD",
    "method": "cash_pickup",
    "amount": "120.00",
    "beneficiary": {
      "name": "Miguel Zambrano Loor",
      "document_value": "1309876543",
      "sender_name": "Ana Torres Silva"
    },
    "idempotency_key": "ec-cash-6612"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "EC",
    "currency": "USD",
    "method": "cnb",
    "amount": "60.00",
    "beneficiary": {
      "name": "Rosa Cedeño Vera",
      "document_value": "0801234567",
      "sender_name": "Ana Torres Silva"
    },
    "idempotency_key": "ec-cnb-7703"
  }'

{
  "payout_id": "9f3a…",
  "country": "EC",
  "currency": "USD",
  "method": "bank_transfer",
  "local_amount": "250.00",
  "fx_rate": "1",
  "usdt_amount": "250.000000",
  "fee": "0.300000",
  "total_debit": "250.300000",
  "status": "processing"
}

Ecuador is dollarized: the local currency IS the USD (fx_rate: "1").
document_value is the beneficiary’s cédula; document_type accepts IDCD (national ID, default), CCPT (passport) or TXID (RUC).
On bank_transfer, omitting bank_code targets an account at the corridor’s issuing bank; for another bank send the bank_code from the catalog (GET /v1/payouts/banks?country=EC) plus account_type (checking or savings).
Optional structured names (given_name, middle_name, first_surname, second_surname and their sender_* counterparts): send them when you have them — they take precedence over the automatic split of name.
The final status arrives via the payout_status_changed webhook (with periodic reconciliation as backup).

Bank transfer in PYG:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PY",
    "currency": "PYG",
    "method": "bank_transfer",
    "amount": "500000",
    "beneficiary": {
      "name": "Sofia Benitez",
      "tax_id": "4123456",
      "bank_code": "0011",
      "account_number": "600123456"
    },
    "idempotency_key": "py-bank-9917"
  }'

{
  "payout_id": "d4e7…",
  "country": "PY",
  "currency": "PYG",
  "method": "bank_transfer",
  "local_amount": "500000",
  "fx_rate": "6055.76",
  "usdt_amount": "82.566020",
  "fee": "0.300000",
  "total_debit": "82.866020",
  "status": "processing"
}

name accepts up to 35 characters in this corridor.

QR payout

In Bolivia (the local interoperable QR) and Brazil (PIX QR, including the “copia e cola” code) you can also pay a collection QR in two steps: scan and confirm. Scanning is free; you are only charged on confirm, exactly like a regular payout (your rate + fixed fee). Without country/currency Bolivia (BOB) is assumed; for Brazil send country: "BR" and currency: "BRL".

1. Scan the QR (free)

Bolivia
Brazil (PIX QR)

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_payload": "<QR content>",
    "currency": "BOB"
  }'

Returns the recipient’s data so the user can confirm who they are paying:

{
  "scan_id": "…",
  "provider_reference": "…",
  "beneficiary_name": "Juan Quispe",
  "destination_account": "…",
  "amount": "700.00",
  "currency": "BOB",
  "glosa": "",
  "status": "…"
}

qr_payload takes the raw PIX QR content (the EMV BR Code) or the “copia e cola” code — they are the same string:

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "qr_payload": "00020126360014br.gov.bcb.pix0114+5511998765432520400005303986540575.005802BR5913LOJA DA MARIA6009SAO PAULO62110507PED423163040BF9"
  }'

The scan decodes the BR Code locally (validating its checksum) and returns the destination PIX key, the merchant name and the amount when the QR carries a fixed one:

{
  "scan_id": "PIXSCAN-…",
  "provider_reference": "<the same EMV payload>",
  "beneficiary_name": "LOJA DA MARIA",
  "destination_account": "+5511998765432",
  "amount": "75.00",
  "currency": "BRL",
  "glosa": "",
  "status": "scanned"
}

An empty amount means an open-amount QR: you decide how much to pay on confirm. With a fixed amount, the confirm must send exactly that amount.
Static PIX QRs are supported (the printed/reusable ones with the key embedded). A dynamic QR (payload carrying the PSP’s URL instead of a key) answers 400 with dynamic pix qr codes are not supported yet — ask the beneficiary for their PIX key and use the pix method.
A tampered or truncated payload answers 400 (invalid CRC checksum).

2. Confirm the payment (charged here)

Bolivia
Brazil (PIX QR)

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_reference": "<from the scan>",
    "amount": "700.00",
    "currency": "BOB",
    "description": "QR lunch payment",
    "idempotency_key": "qr-2026-07-07-a"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "provider_reference": "<from the scan>",
    "amount": "75.00",
    "description": "Order 4231",
    "idempotency_key": "qr-br-2026-07-16-a"
  }'

amount is always required: with a fixed-amount QR it must match exactly — otherwise you get 422 with the payout in status: failed (status_message: "amount mismatch: the qr requires exactly 75.00 BRL") and the refund already applied; fix the amount and retry with a new key. With an open-amount QR whatever you send is what gets paid.
A static PIX QR is reusable by design (a shop’s printed QR gets paid many times): you can pay it again with a different idempotency_key. A failed attempt does not burn the QR.
The payment travels through the same PIX rail as the pix method (24/7); the QR’s txid goes with it so the merchant reconciles automatically.

usdt_amount + fixed fee is debited at your rate, just like a bank_transfer.
The result is synchronous: the response already carries the final state (completed, or failed with an automatic refund) — no waiting.
Retries with the same idempotency_key return the original payout. In Bolivia the scan reference is single-use (a scanned QR can only be paid once); in Brazil a static PIX QR is reusable and each payment carries its own key.

Common errors

HTTP	`error`	What to do
400	`idempotency_key_required`	Send the key in body or header
400	`beneficiary_required`	Include the `beneficiary` object
402	`insufficient_funds`	Fund the account; the payout was not created
403	`account_blocked`	The account is not active; contact the CBPay team
403	`service_disabled`	Payouts is not enabled for your account — see services
422	`currency_not_supported`	No FX rate for that currency
422	(payout with `status: failed`)	The corridor rejected the data; the debit was already refunded — fix `beneficiary` and retry with a new key
503	`channel_unavailable`	The payout channel is temporarily unavailable; retry later with the SAME `idempotency_key`

Immediate rejection vs later failure

If the processor rejects the payout at creation, you receive 422 with the object in status: failed and the refund already applied. If it fails later (e.g. the destination account does not exist), the webhook arrives with status: failed and the automatic refund happens at that moment.

Reading `status_code` on a failed payout

`status_code`	Meaning	Action
`core_rejected`	The processor rejected the operation at creation (invalid beneficiary data, corridor unavailable)	Read `status_message`, fix the data and create a new payout with a new key
`channel_unavailable`	The payout channel became temporarily unavailable	Retry later; the refund (if a debit happened) is already applied
another code	Later rejection by the banking rail (e.g. destination account closed)	Same: fix the data and create a new operation
(empty)	Generic corridor failure	Check `status_message`; if unclear, contact support with the `payout_id`

In every case the refund is already applied — verify it with the payout_refund entry in movements.

A payout in processing cannot be cancelled through the API: the rail already has it. Wait for the final state via webhook or GET — it always arrives, with an automatic refund on failure.

Getting Started

Concepts

Integration flows

Products

Integration

Resources

1. Discover the available corridors

2. Create the payout

Paying from another balance (`settlement_asset`)

3. Receive the final state

Payout statuses

Reads and history

Examples by country

Beneficiary fields per corridor

QR payout

1. Scan the QR (free)

2. Confirm the payment (charged here)

Common errors

Immediate rejection vs later failure

Reading `status_code` on a failed payout

​1. Discover the available corridors

​2. Create the payout

​Paying from another balance (settlement_asset)

​3. Receive the final state

​Payout statuses

​Reads and history

​Examples by country

​Beneficiary fields per corridor

​QR payout

​1. Scan the QR (free)

​2. Confirm the payment (charged here)

​Common errors

​Immediate rejection vs later failure

​Reading status_code on a failed payout

1. Discover the available corridors

2. Create the payout

Paying from another balance (`settlement_asset`)

3. Receive the final state

Payout statuses

Reads and history

Examples by country

Beneficiary fields per corridor

QR payout

1. Scan the QR (free)

2. Confirm the payment (charged here)

Common errors

Immediate rejection vs later failure

Reading `status_code` on a failed payout