Skip to main content
A payment sends money from one of your accounts to one of a recipient’s destinations. Scopes: payments:write to send and quote, payments:read to check. payments:write moves money: give it only to the service that needs it.

Same currency

When the account and the destination hold the same currency, send the amount directly.
The amount is reserved as soon as the payment is accepted, so it leaves your available balance at once.

Different currencies

To pay an NGN bank account from a GBP account, lock a rate first with an FX quote, then send with it.
1

Quote

Fix the side you care about. Usually that’s what the recipient receives:
Show the person amountFromMinorUnits (“you send £28.82”) and the rate. To spend an exact amount instead, send amountFromMinorUnits and leave out amountToMinorUnits.
2

Send with the quote

Send the source side: minorUnits and currency must match the quote’s amountFromMinorUnits and from.
  • Use the quote’s amounts, never the rate. Multiplying by rateMicro won’t reliably reproduce the quoted amounts.
  • Quotes expire. Read validForSeconds rather than assuming a lifetime; it varies by currency pair. Fetch a new quote when it runs out.
  • Quotes are single-use. Once a payment uses one, it can’t be used again, even if that payment then fails. Get a new quote to retry with a new idempotency key.

Track the outcome

A 201 means the payment was accepted, not that it has arrived. Read status: Poll until the status is final:
Webhooks for payment outcomes are coming. Until then, poll GET /v1/transfers/{id} while a payment is pending or processing.

When a payment is refused

Nothing is reserved or sent when a payment is refused. A 202 means one of your approval policies holds the payment. The amount is set aside and nothing is sent until it’s approved in the dashboard; if it’s rejected or expires, the amount is released. A 200 (rather than 201) means you sent an idempotency key that already named a payment. That payment is returned and nothing is sent again.