Skip to main content
Breaking change — 2026-11-13. BOB, MXN, ARS and CLP ledger balances, plus BANK_* mirrors, are Banking-only. Platform payouts, swaps, internal transfers, cards, checkout, POS and fees reject fiat settlement with HTTP 400. Legacy accounts keep their explicit USDT default; new accounts use USD as the principal balance. Use Banking for fiat operations.
A payout sends money in local currency to a bank account in the destination country. The amount converts from local currency to your account’s default balance at your account’s rate (the one from GET /v1/rates) and the reported equivalent plus fee (the fixed fee, when configured) is debited from that default balance. Legacy accounts with an explicit USDT default continue to debit USDT. 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:
Available corridors and methods: 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):

2. Create the payout

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:
At that moment your balance already reflects the debit: total_debit moved from available into held (on the settlement_asset balance).

US/USD remittance payouts

For a wire or swift payout in USD to the United States, set options.is_remittance to the string "true" when you are paying on behalf of a third party. This option is only supported on US/USD wire and swift; it is rejected on ach and ignored on other rails.
Response 202 Accepted:
The operator selects the Ultimate Debtor from the live bank list before release. If no debtor is selected, the payout returns to the queue instead of being released without that information. The debtor is selected by the operator; it is not supplied by the integrator. Do not resend the payout to change it: read the existing payout and keep the same idempotency key.
Do not send is_remittance as a JSON boolean. The accepted value is the string "true". An ach payout with this option returns 400; the option is ignored on rails other than US/USD wire and swift.
bank_reference — the bank’s own id for the transfer. On US ACH, wire and SWIFT it is the CBF reference returned immediately at create (the payout stays processing until the bank confirms). On other corridors it stays empty ("") until the payout is completed. It is the value the beneficiary can use to cross-check the payment with their bank, and it also appears in the payout_status_changed webhook, the PDF receipt, the payouts CSV export and the statement. Payout responses, webhooks, CSV and receipts also expose uetr (UETR/SWIFT gpi) and imad (domestic wire/ACH), both empty until reported by the bank; use the public transaction tracker for live status and the same receipt.

Paying from another balance (settlement_asset)

The default debit comes from USD; use PUT /v1/settlement to change it. 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:
  1. CLP → USDT at your rate: 100000 / 950.25 = 105.235465 USDT.
  2. + fixed fee: 105.235465 + 0.30 = 105.535465 USDT (total_debit).
  3. USDT → BTC at the effective settlement price (settlement_rate 109029.34070000): 105.535465 / 109029.3407 = 0.00096795 BTC (rounded up to the satoshi).
  4. Debit and hold in BTC: settlement_amount 0.00096795 leaves your BTC balance; the beneficiary receives their 100,000 CLP exactly as always.
If the payout fails, the exact settlement_amount is refunded to your BTC balance — never re-quoted. If the BTC/GOLD/SILVER/PLATINUM 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). For same-currency BOB, MXN or ARS settlement, see Fiat payout settlement.

Technical screening can be pending

CBPay screens the beneficiary before it debits your balance or calls the core. If the screening service is temporarily unavailable and the technical screening queue is available, the payout is persisted and the create call returns 202 Accepted with the payout resource in status: "pending":
While it is pending there is no debit, hold, ledger entry, core dispatch or receipt_url. Replaying with the same idempotency key returns the same payout with idempotency_hit: true; it never creates a second operation. When the screening worker receives process, the existing payout enters the normal debit and dispatch flow. A valid hold goes to the transactional firewall. A later rejected result ends the queued payout as failed with no debit. After process is accepted, the same payout can remain status: "pending" while the debit and dispatch are reconciled. The API and payout_status_changed webhook expose these durable transition codes:
  • compliance_dispatch_pending: screening passed, the debit/hold exists and funds_debited: true, but the core dispatch has not completed.
  • compliance_dispatching: the dispatch claim is in progress.
  • core_unreachable: the dispatch or local settlement is ambiguous and is waiting for reconciliation; do not create a second payout.
These transitions are not a new payout operation. Keep the same idempotency_key, read the payout, and wait for the next status event. Once the payout is final, completed consumes the hold and failed refunds the exact debit. Final status events use the durable event path and include the normal receipt fields. The technical compliance_check_unavailable response remains applicable when the payout cannot be placed in the pending queue, and to flows that do not have this queue. It does not replace the existing validation, security or compliance_hold contracts.

Pre-debit failure is not a refund

If screening or a hard compliance gate fails before the debit path starts, the same payout can finish as failed with predebit_failure: true and funds_debited: false. The response and its payout_status_changed event omit receipt_url, because there was no debit, hold or receipt to reverse. This is different from a post-debit failed payout, where the exact debit is refunded before the terminal event. For rate provenance and indicative FIFO quotes, see Payout rate sources and indicative FIFO quotes.

Argentina: resolve a bank alias before paying

Resolve and confirm the holder before creating the payout (10 lookups/minute/account). Request: GET /v1/payouts/ar-alias/resolve?alias=julieta.fernandez. Response: {"alias":"julieta.fernandez","account_number":"2850590940090418135201","account_type":"CBU","tax_id":"27234567891","holder_name":"Julieta Fernandez"}. Create POST /v1/payouts with account_number set to the original alias and the returned tax_id/name; dispatch re-resolves it and records destination_alias in evidence. alias_unresolvable is deterministic; beneficiary_lookup_unavailable is temporary. See Errors.

3. Receive the final state

Subscribe to the payout_status_changed event (webhooks):
  • completed: the money arrived; the hold is consumed.
  • failed: the full debit is refunded automatically (payout_refund in your ledger).
status_message is the optional, normalized detail accompanying status_code; it can be empty when the core has no additional message. You can also query at any time:

Payout statuses

Reads and history

Every payout can be read individually and the listing accepts filters:
from/to use YYYY-MM-DD (organization timezone, both inclusive); an invalid date responds 400 invalid_range. method filters by the live payout catalog, while search performs a case-insensitive partial match on the payout ID, bank reference or idempotency key.
Last modified on November 17, 2026