Skip to main content

Settlement

Settlement is the process by which a payment reaches its final state at the rail that carries it.

CashXChain abstracts the complexity of settlement while still exposing enough information for businesses to operate confidently.

Settlement depends on the scheme​

A payout leaves from the rail that holds its source account and settles through the scheme its corridor uses:

  • Domestic bank transfer schemes.
  • International wires (SWIFT).
  • Transfers on our partner's own books, between two CashXChain businesses.

In production no payout settles through a stablecoin yet. In the sandbox, a send from a digital-asset account settles on chain — settled with its tx_hash once the provider reports it — or through the bank scheme it pays out over; those the provider's sandbox never finishes, the sandbox settles itself (simulated: true) — see Sandbox behaviour.

Settlement states​

Settlement is visible as the payout's status: submitted when the rail has accepted the instruction, processing while it executes, settled when the money has arrived — with settled_at set — and failed when it did not. The status model also has returned, for money the receiving bank sends back, and cancelled; today's rails report neither. The full lifecycle is in Payouts.

Speed expectations​

Some schemes confirm in seconds. Others depend on banking cut-off times, beneficiary bank processing, compliance review, or partner operating windows; SWIFT can take days. The API does not promise a settlement time — follow the payout's status.

In the sandbox every payout from a bank account settles inside the request; a digital-asset send does not. Build for the production timing — see Environments.

Finality​

Finality means different things across schemes. Internal partner settlement, SEPA, ACH, wires and other domestic schemes each have different confirmation and return characteristics.

CashXChain normalizes these differences into one status model, but settled is not a guarantee against a later return by the receiving bank. Today's rails do not report returns to us; reconcile against statements.

Settlement references​

A payout carries two references:

  • The CashXChain payout id.
  • The rail's own reference, partner_payment_id.

The reference shown to the beneficiary and the fx_quote_id you sent are not returned on the payout. Keep them with the payout id in your own records.

Reconciliation​

Use settlement references and statements to match CashXChain payments to invoices, ERP entries, customer orders, or partner reports.