Skip to main content
POST
Preview a transfer
Preview before you show a confirmation screen. totalDebit is what actually leaves the account — sourceAmount plus fee — and it is the figure a payer should be asked to approve.
Preview does not check the balance and does not reserve anything. It can succeed and the transfer can still fail with insufficient_funds a moment later.
It also does not consume the destination or the quote, so previewing twice is free.

Error codes

Authorizations

Authorization
string
header
required

A secret API key, sent as Authorization: Bearer sk_test_… in sandbox or Bearer sk_live_… in live.

Body

application/json

Amounts are positive integers of minor units, as strings. Send exactly the one matching amountSide for a same-currency transfer; for a cross-currency one the amounts come from the quote.

sourceAccountId
string
required

Must be active, debitable, in sourceCurrency, and not a customer wallet.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

destinationId
string
required

An unexpired, unspent destination.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

sourceCurrency
enum<string>
required
Available options:
NGN,
USD,
GBP,
EUR,
GHS,
ZAR,
UGX,
CAD,
MXN,
AED,
USDC
destinationCurrency
enum<string>
required
Available options:
NGN,
USD,
GBP,
EUR,
GHS,
ZAR,
UGX,
CAD,
MXN,
AED,
AUD,
SGD,
HKD,
KES,
TZS,
BRL,
CNY,
XAF,
PHP,
USDC
amountSide
enum<string>
required
Available options:
source,
destination
sourceAmount
string

A positive integer number of minor units.

Pattern: ^[1-9]\d*$
Example:

"2500000"

destinationAmount
string

A positive integer number of minor units.

Pattern: ^[1-9]\d*$
Example:

"2500000"

fxQuoteId
string

Required when the currencies differ, and rejected as a mismatch if it was quoted for a different account, destination, side, or amount.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

Response

Successful response.

sourceCurrency
enum<string>
required
Available options:
NGN,
USD,
GBP,
EUR,
GHS,
ZAR,
UGX,
CAD,
MXN,
AED,
USDC
destinationCurrency
enum<string>
required
Available options:
NGN,
USD,
GBP,
EUR,
GHS,
ZAR,
UGX,
CAD,
MXN,
AED,
AUD,
SGD,
HKD,
KES,
TZS,
BRL,
CNY,
XAF,
PHP,
USDC
sourceAmount
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

destinationAmount
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

fee
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

totalDebit
string
required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$
Example:

"25000.00"

routeId
string | null
required

A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

scheme
string
required
fxQuoteId
string | null
required

A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

quoteExpiresAt
string<date-time> | null
required
Example:

"2026-08-14T09:00:00.000Z"