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
rateMicrowon’t reliably reproduce the quoted amounts. - Quotes expire. Read
validForSecondsrather 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
A201 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.