Skip to main content

Payments

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

API shapes

This page describes the normalized, business-facing model. For the exact request/response shapes available today, see the Payments API — money movement is created with POST /v1/transfers and read back as transactions (GET /v1/transactions) and payments (GET /v1/payments).

Payment object (normalized model)​

A normalized payment record includes, depending on route:

  • 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 recipient/contact is usable.
  3. Request and (if needed) lock an FX quote.
  4. Create the transfer (POST /v1/transfers).
  5. Track the resulting transaction status.
  6. Handle executing, failed, rolled_back, and completed states.
  7. Reconcile with transactions and 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.