Skip to main content

Payments API

The Payments API creates and tracks payment instructions.

Create a payment​

POST /v1/payments
{
  "source_account_id": "acct_8mJ3...",
  "source_wallet_id": "wlt_2Gk4...",
  "beneficiary_id": "bnf_6rK2...",
  "quote_id": "fxq_9Xc2...",
  "amount": "25000.00",
  "currency": "EUR",
  "purpose": "supplier_payment",
  "reference": "INV-2026-1042",
  "metadata": {
    "invoice_id": "INV-2026-1042"
  }
}

Always send X-Idempotency-Key.

Response​

{
  "id": "pay_6pD3...",
  "status": "created",
  "amount": "25000.00",
  "currency": "EUR",
  "beneficiary_id": "bnf_6rK2...",
  "quote_id": "fxq_9Xc2...",
  "created_at": "2026-06-01T09:00:12Z"
}

Retrieve a payment​

GET /v1/payments/{payment_id}

List payments​

GET /v1/payments?account_id=acct_8mJ3&limit=50

Cancel a payment​

POST /v1/payments/{payment_id}/cancel

Cancellation is only possible before the payment reaches a non-cancellable execution state.

Payment timeline​

GET /v1/payments/{payment_id}/timeline

Use the timeline for support, audit, and reconciliation.

Webhook events​

Payment changes produce events such as:

  • payment.created
  • payment.requires_action
  • payment.screening
  • payment.authorized
  • payment.processing
  • payment.completed
  • payment.failed
  • payment.returned