Skip to main content

Payments

Payments are the core resource in CashXChain. A payment — a payout in the API — is a business instruction to move money from one of your accounts to a beneficiary, with a defined amount, currency, optional purpose and FX quote, and a lifecycle.

Payment types​

CashXChain is designed to support several payment patterns:

  • Supplier payments: pay vendors, manufacturers, contractors, or service providers.
  • Platform payouts: pay sellers, freelancers, merchants, or marketplace participants.
  • Treasury transfers: move funds between entities, accounts, currencies, or operating balances.
  • Invoice payments: pay against structured invoice references.
  • Same-network transfers: move value between CashXChain-enabled businesses where supported.
  • Local payouts: settle funds through partner rails in the beneficiary currency.

Delivery methods​

A payout is delivered on the rail that holds its source account, through the scheme the corridor uses:

  • Direct bank transfer to the beneficiary — SEPA, Faster Payments, ACH, Fedwire, and equivalent domestic schemes.
  • International wire — SWIFT.
  • Same-network transfer between two CashXChain businesses.

In production no payout uses a stablecoin yet; amounts, fees and statements are in business currencies.

In the sandbox, a payout can also leave from a digital-asset account — USDC, EURC or another stablecoin — on the same POST /v1/banking/payouts:

  • On chain, to an address on the wallet's chain or on another chain.
  • To an IBAN, paid out as EUR over SEPA.
  • To a US, UK, Mexican or Brazilian bank account, over ACH or wire, Faster Payments, SPEI or Pix.
  • To another CashXChain business by its @handle, wallet to wallet.
  • Between your own accounts: a swap between USDC and EURC, USDC sent back to your EUR account, EUR converted into your USDC account.

Each is sent with the travel-rule data its destination needs; API keys send to third parties only to trusted beneficiaries a person approved. See Sending.

See Rails for the sending and funding rails.

Payment lifecycle​

A payout moves through one lifecycle whichever rail carries it: created → submitted → processing → settled, with failed and cancelled possible before settlement and returned after it. Accepted is not arrived: only settled means the money reached the beneficiary. The statuses, every allowed transition, and how long each step takes in sandbox and production are in Payouts.

Idempotency​

Every payout carries an Idempotency-Key. Retrying with the same key returns the payout that was already created instead of paying twice. See Idempotency and the Quickstart for a payout from start to finish.

Amounts and currencies​

Amounts are represented as strings to avoid floating-point errors. Currency codes use ISO 4217.

Payment purpose​

Some corridors require a purpose of payment. The codes a corridor accepts are listed in payment_purposes by GET /v1/banking/corridors; pass one as purpose_of_payment on the payout. See Beneficiaries.

Operational controls​

A payout can be refused before anything is sent: by your plan's limits (422 plan_limit_exceeded), by an account that is not yet verified (403 account_not_verified), by the receiving bank's payee-name check (422 payee_name_mismatch), by an expired FX quote (409 quote_expired), or by a platform-wide pause or an account hold (503 platform_paused, 403 account_on_hold) — see Payouts.

Reconciliation​

Each payout has a stable id, the rail's own reference (partner_payment_id), and timestamps for when it was created, submitted and settled. The reference you send is shown to the beneficiary but not returned on the payout, so keep it with the payout id in your own records. Statements list the booked lines with running balances. Use them to reconcile against invoices, ERP entries and bank statements — see Accounts.