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:
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
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).202 Accepted:
total_debit moved
from available into held (on the settlement_asset balance).
US/USD remittance payouts
For awire 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.
202 Accepted:
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:
- 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_rate109029.34070000):105.535465 / 109029.3407 = 0.00096795 BTC(rounded up to the satoshi). - Debit and hold in BTC:
settlement_amount0.00096795leaves your BTC balance; the beneficiary receives their 100,000 CLP exactly as always.
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 returns202 Accepted with the payout resource in status: "pending":
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 andfunds_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.
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 asfailed 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 thepayout_status_changed event (webhooks):
completed: the money arrived; the hold is consumed.failed: the full debit is refunded automatically (payout_refundin 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.