Payments

Payments are the core resource in CashXChain. A payment represents a business instruction to move value from one account or balance to a beneficiary, with a defined amount, currency, purpose, quote, route, metadata, and 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 payment can be delivered through any rail CashXChain supports for the corridor and account, including:

• Direct bank transfer to the beneficiary (SEPA, SEPA Instant, FPS, ACH, wire, and equivalent local schemes).
• Local payout networks through regulated partners.
• Stablecoin transfer to a beneficiary on a supported chain, where set up and compliant.
• Same-network transfer between two CashXChain-enabled accounts.

Stablecoins are also used internally by CashXChain as a settlement medium between partners and corridors. The business-facing API and dashboard remain fiat-native — amounts, fees, and statements are always quoted in business currencies.

See Rails for a full breakdown of sending and funding rails, on-chain vs off-chain routing, and how the routing engine selects between them.

Payment lifecycle

A payment moves through a normalized lifecycle even when the underlying partner or rail has its own status model.

Status	Meaning
created	The instruction was accepted by CashXChain.
requires_action	More information, approval, or documents are required.
screening	Compliance, sanctions, or risk checks are in progress.
authorized	The payment is approved for processing.
processing	The selected partner or rail is executing the payment.
settling	Funds are moving or awaiting final confirmation.
completed	The payment completed successfully.
failed	The payment could not be completed.
cancelled	The payment was cancelled before completion.
returned	The payment was completed or sent but later returned by a downstream party.

Idempotency

Always provide an X-Idempotency-Key when creating a payment. This prevents duplicate payments if your system retries after a timeout.

curl -X POST https://api.sandbox.cashxchain.com/v1/payments \
  -H "Authorization: Bearer $CXC_API_KEY" \
  -H "X-Idempotency-Key: invoice-2026-1042-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source_account_id": "acct_8mJ3...",
    "beneficiary_id": "bnf_6rK2...",
    "quote_id": "fxq_9Xc2...",
    "amount": "25000.00",
    "currency": "EUR",
    "purpose": "supplier_payment",
    "reference": "INV-2026-1042"
  }'

Amounts and currencies

Amounts are represented as strings to avoid floating-point errors. Currency codes use ISO 4217 where possible. Stablecoin settlement assets may appear in technical metadata where relevant, but business-facing fields remain fiat-first.

Payment purpose

A purpose of payment may be required depending on the corridor, amount, partner, and beneficiary country. Examples include:

• supplier_payment
• contractor_payment
• invoice_payment
• marketplace_payout
• treasury_transfer
• software_services
• goods_import
• professional_services

Operational controls

Payments can be restricted by account limits, user permissions, required approvals, risk score, corridor availability, partner availability, quote expiry, or missing beneficiary information.

Reconciliation

Each payment includes stable IDs, external references, fee breakdown, quote information, timestamps, beneficiary details, and timeline events. Use these fields to reconcile against invoices, ERP entries, and bank statements.