Skip to main content

Payments

The platform payment resource represents a normalized instruction and lifecycle across all supported routes.

Payment object​

A payment object contains:

  • id: CashXChain payment ID.
  • source_account_id: account that owns the payment.
  • source_wallet_id: balance container to debit.
  • beneficiary_id: recipient.
  • quote_id: FX quote, if conversion is involved.
  • amount: amount to debit or send.
  • currency: source currency.
  • target_amount: expected beneficiary amount, if known.
  • target_currency: beneficiary currency.
  • status: normalized lifecycle status.
  • purpose: business reason.
  • reference: customer-visible reference.
  • metadata: customer-defined key-value pairs.
  • timeline: status history.
  • fees: fee breakdown.

Create payment flow​

  1. Confirm the account is active.
  2. Confirm the beneficiary is usable.
  3. Request a quote if FX is required.
  4. Create the payment with an idempotency key.
  5. Wait for webhooks.
  6. Handle requires_action, failed, returned, and completed states.
  7. Reconcile with statements.

Metadata​

Use metadata to attach internal references:

{
  "metadata": {
    "invoice_id": "INV-2026-1042",
    "erp_vendor_id": "VEN-4481",
    "department": "supply_chain",
    "created_by": "treasury-bot"
  }
}

Metadata is not a substitute for required compliance fields. Do not store sensitive secrets in metadata.

Cancellation​

Cancellation is only possible while a payment is still cancellable. Once a partner or rail has executed a step, cancellation may no longer be available and a return or reversal process may be required.

Returns​

A completed payment may later be returned by a beneficiary bank or downstream rail. Your system should handle payment.returned events and reconcile the corresponding balance movement.