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.

Common errors

Immediate rejection vs later failure

If the processor rejects the payout at creation for a correctable business reason, you receive 422 with the object in status: failed and the refund already applied. Fix the beneficiary or request data and create a new payout with a new key. A channel or treasury shortfall is different: the platform can keep the payout in in_review instead of failing it immediately, so no new payout should be created until the review outcome says what to do. When a payout is in in_review, the account-facing message is intentionally generic: it is under review and will complete automatically once released. Do not correct beneficiary data for this state. If the review is approved but the original dispatch key has already been consumed, the approval returns reissue_required; create a new payout with a new idempotency_key only then. CBPay never re-issues the money operation automatically.

Reading status_code on a failed payout

For a terminal failed payout, the account-facing message says that it could not be completed and the funds were returned. Verify the refund with the payout_refund entry in movements. A payout still in in_review is not terminal; wait for its review result instead of assuming that a refund or a new dispatch has happened.
A payout in processing cannot be cancelled through the API: the channel already has it. A payout in in_review is also not a client-side cancellation flow; wait for the review result. For either state, wait for the final state via webhook or GET. A terminal failure returns the funds; an approval that reports reissue_required requires a new client-created operation with a new key.

FAQ

At creation: the payout debits and holds the funds immediately. If the payout fails, the exact debited amount (fee included) is refunded automatically.
No — once dispatched to the rail it resolves to completed or failed on its own. Subscribe to payout_status_changed for the final state.
The rate quoted at creation (returned as fx_rate), frozen for that operation. Your agreed spread is already inside the rate.
Yes — set a per-account default (PUT /v1/settlement) or override per payout with settlement_asset (USDC, BTC, GOLD). Refunds return the exact settled amount, never re-quoted.
The beneficiary screening is temporarily unavailable, but CBPay persisted the payout in its technical screening queue. No balance was debited, no hold or ledger entry exists, the core was not called and there is no receipt_url yet. Replay with the same idempotency key returns the same resource. Wait for the payout_status_changed event or poll the payout; it will continue after process, enter the firewall for a valid hold, or become failed without a debit if the result is rejected.
The payout was held for review and was not processed: no funds moved and your idempotency_key was not consumed. The portal shows a copyable reference line with UTC time, error code and short request ID. Include it when you contact support; the exact compliance reason is not disclosed.
The payout is under review and the account-facing message is generic: it will complete automatically once released. This state can protect a payout when the channel or its treasury is temporarily unavailable. Do not change the beneficiary or create a second payout while it is in review. If approval returns reissue_required, create a new payout with a new idempotency key; CBPay never re-issues it automatically.
Some temporary channel conditions are not caused by your beneficiary data. Replay the direct 503 with the same idempotency key. If the payout was placed in in_review, wait for the review outcome; only an explicit reissue_required result authorizes a new payout with a new key.
Retry with the same idempotency_key: you get the original payout back (idempotency_hit: true) — never a duplicate. A new key is a new, independent payout.
US bank-rail payouts are paid by the operator by hand. Create already returns the CBF in bank_reference and stays processing until the bank confirms. Estimates: ACH 24–48 business hours, wire/Fedwire same business day (up to 24 hours), SWIFT 24–48 business hours (potentially longer depending on the receiving bank). Listen to payout_status_changed; failures refund the debit.
For payout errors and the 422 destination_recently_rejected retry sequence, see Errors and Destination rejection protection.

US/USD payment purpose and validation

For US/USD bank-rail payouts (ach, wire and swift), options.purpose is mandatory. The API accepts either the visible label or its code, case-insensitively. The accepted catalog is: beneficiary.account_type is required for both ach and wire and must be checking or savings (case-insensitive). swift does not use this field. For wire and swift, amounts below USD 25 return 422 amount_below_minimum. Annex-B beneficiary or bank countries (CU, IR, KP, SY) return 422 prohibited_country. These checks happen before any debit. The normalized validation errors are invalid_beneficiary, invalid_amount, amount_below_minimum, prohibited_country, purpose_required, invalid_options and supporting_document_required. Read message for the exact field to fix. Do not retry a rejected request unchanged; after a timeout or 5xx, reuse the same idempotency key.
Last modified on November 14, 2026