Skip to main content

Payments guide

A robust payment integration must handle success, failure, review, retries, duplicate events, quote expiry, and reconciliation.

  1. Create or retrieve beneficiary.
  2. Request FX quote if required.
  3. Create payment with idempotency key.
  4. Store payment ID and quote ID.
  5. Listen for webhooks.
  6. Handle requires_action.
  7. Reconcile on completion.

Idempotency strategy​

Use a stable business identifier as part of your idempotency key, such as invoice ID plus attempt number.

invoice-INV-2026-1042-payment-attempt-1

If you retry the exact same request with the same key, CashXChain returns the original result. If you reuse the same key with a different body, the API returns idempotency_conflict.

Payment references​

Use references that finance teams recognize:

  • Invoice number.
  • Purchase order.
  • Supplier ID.
  • Customer order ID.
  • Internal treasury transfer ID.

Handling requires_action​

A payment may require action because of missing data, expired quote, beneficiary review, account restriction, approval requirement, or partner request.

Your integration should surface the action to the correct user or operations team.

Handling returns​

Returns can happen after apparent completion on some rails. Always listen for payment.returned and reconcile the returned amount as a separate event.

Polling fallback​

Use webhooks as the primary source of updates. Poll payment status only as a fallback or during reconciliation.