Skip to main content
POST
Afriex SDK
For a SWAP, the API computes the amount you leave out at the live exchange rate. A SWAP with both amounts is rejected.
Want to show a customer what a withdrawal will cost before you create it? Quote a Withdrawal returns the rate, fee, and both amounts without creating anything, and a create with the same inputs charges the quoted amounts.
Testing in sandbox? Sandbox transactions settle automatically in about 5 minutes and send the TRANSACTION.UPDATED webhook. Pick the outcome with the payment method’s last four digits (e.g. 0001 fails, 0002 requires OTP for mobile money, 0003 stays pending until you call /simulate). Add SIMULATE_INSTANT anywhere in meta.reference to settle in about 30 seconds. Full reference: Testing in Sandbox.

Authorizations

x-api-key
string
header
required

Static business API key issued from the dashboard. A business can provision multiple API keys, each scoped to a configurable set of permissions (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Manage your keys and their permissions under Developer → API keys in the dashboard.

A request whose key does not carry the permission the target endpoint requires is rejected with 401 Unauthorized, the same response an unrecognised, malformed, revoked or disabled key returns. The API does not distinguish the two cases on the wire.

See the Permissions reference for the permission each endpoint requires.

Headers

x-api-signature
string

Signature of the request payload, used for request authentication where payload signing is enabled for your business.

x-api-version
string

API version in ISO 8601 format. The only supported version is 2026-05-18, which is also the default when the header is omitted. Any other value is rejected with a 400 Bad Request.

Body

application/json

Send funds to a customer's destination payment method. This is the default when type is omitted. Provide sourceAmount, destinationAmount or both; sending sourceAmount alone lets the API compute the destination side at the live forward rate.

customerId
string
required

The unique identifier of the customer. Required for DEPOSIT and WITHDRAW transactions. Not required for SWAP, if omitted, the transaction runs against the business wallet.

Example:

"69528240ba52c13b669fb239"

destinationCurrency
string
required

The 3-letter ISO 4217 currency code of the destination currency (e.g., USD, NGN). Upper case, and a currency Afriex supports.

Pattern: ^[A-Z]{3}$
Example:

"USD"

sourceCurrency
string
required

The 3-letter ISO 4217 currency code of the source currency (e.g., USD, NGN). Upper case, and a currency Afriex supports.

Pattern: ^[A-Z]{3}$
Example:

"NGN"

destinationId
string
required

Required for WITHDRAW transactions. The id of the destination payment method that money will be sent to.

Example:

"690df3281c11eea59108fcaf"

meta
object
required

Transaction metadata. idempotencyKey and reference are required.

type
enum<string>

The type of transaction. DEPOSIT pulls funds from the customer's source payment method (requires sourceId). WITHDRAW sends funds to the customer's destination payment method (requires destinationId). SWAP converts funds between currencies within the Afriex wallet (requires sourceCurrency, destinationCurrency, meta, and exactly one of sourceAmount or destinationAmount; the API computes the other side at the live exchange rate, and sending both is rejected). If omitted, defaults to WITHDRAW.

Available options:
WITHDRAW
sourceAmount

The transaction amount in the source currency. For WITHDRAW and DEPOSIT, provide sourceAmount, destinationAmount or both: sending sourceAmount alone lets the API compute destinationAmount at the live forward rate (useful when you know only how much you want to send, e.g. a SWIFT payout of a fixed source balance). When both are sent, destinationAmount wins unless shouldPreferSourceAmount is true. For SWAP, provide exactly one of sourceAmount or destinationAmount: setting sourceAmount makes the API compute destinationAmount at the live exchange rate.

Required range: x > 0
Example:

"100.50"

destinationAmount

The transaction amount in the destination currency. For WITHDRAW and DEPOSIT, provide sourceAmount, destinationAmount or both: setting destinationAmount fixes the amount, while omitting it and sending sourceAmount lets the API compute destinationAmount at the live forward rate. A request with neither is rejected. For SWAP, provide exactly one of sourceAmount or destinationAmount: setting destinationAmount instead makes the API compute sourceAmount at the inverse rate. Sending both amounts on a SWAP is rejected.

Required range: x > 0
Example:

"100.50"

sourceId
string

Required for DEPOSIT transactions. The id of the source payment method that money will be pulled from.

Example:

"690df3281c11eea59108fcaf"

shouldPreferSourceAmount
boolean

Opt in to deriving destinationAmount from sourceAmount even when both amounts are sent. Defaults to false, which keeps destination-wins semantics so a caller that echoes both amounts still gets the destinationAmount they asked for. Set true to have sourceAmount drive the payout via the forward rate.

correspondentBankName
string

The correspondent (intermediary) bank name for USD payouts (WITHDRAW with destinationCurrency USD and meta.settlement 'request'). Only used as a fallback when the destination payment method lacks it. The payment method's value takes precedence. Must be provided together with correspondentBankAccountNumber.

correspondentBankAccountNumber
string

The correspondent (intermediary) bank account number for USD payouts (WITHDRAW with destinationCurrency USD and meta.settlement 'request'). Only used as a fallback when the destination payment method lacks it. The payment method's value takes precedence. Must be provided together with correspondentBankName.

Response

Transaction created successfully.

data
object