Common errors
Immediate rejection vs later failure
If the processor rejects the payout at creation for a correctable business reason, you receive422 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
When is my balance debited?
When is my balance debited?
At creation: the payout debits and holds the funds immediately. If the
payout fails, the exact debited amount (fee included) is refunded
automatically.
Can I cancel a payout in processing?
Can I cancel a payout in processing?
No — once dispatched to the rail it resolves to
completed or failed on
its own. Subscribe to payout_status_changed for the final state.Which FX rate does my payout use?
Which FX rate does my payout use?
The rate quoted at creation (returned as
fx_rate), frozen for that
operation. Your agreed spread is already inside the rate.Can I pay from a balance other than USDT?
Can I pay from a balance other than USDT?
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.What does status: pending with compliance_pending: true mean?
What does status: pending with compliance_pending: true mean?
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.What does compliance_hold (403) mean?
What does compliance_hold (403) mean?
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.What does status: in_review mean for a payout?
What does status: in_review mean for a payout?
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.Why did a payout return 503 without a beneficiary error?
Why did a payout return 503 without a beneficiary error?
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.How do I retry safely after a timeout or 5xx?
How do I retry safely after a timeout or 5xx?
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.Why is my US ACH/wire/SWIFT payout still processing?
Why is my US ACH/wire/SWIFT payout still processing?
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.422 destination_recently_rejected retry sequence, see
Errors and Destination rejection protection.
US/USD payment purpose and validation
ForUS/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.