Create Transaction
Create a new transaction to process a payment for a customer. Use type: WITHDRAW to send funds to a destination payment method (requires destinationId), type: DEPOSIT to pull funds from a source payment method (requires sourceId), or type: SWAP to convert funds between currencies within the Afriex wallet (requires sourceCurrency, destinationCurrency, meta, and exactly one of sourceAmount or destinationAmount).
type: WITHDRAW to send funds to a destination payment method (requires destinationId), type: DEPOSIT to pull funds from a source payment method (requires sourceId), or type: SWAP to convert funds between currencies within the Afriex wallet. A SWAP requires sourceCurrency, destinationCurrency, meta, and exactly one of sourceAmount or destinationAmount: the API computes the other side at the live exchange rate. Providing both amounts is rejected.
TRANSACTION.UPDATED webhook. Set meta.reference to a value containing fail to test a FAILED outcome, or any other value for SUCCESS. To exercise OTP-required deposits, add SIMULATE_OTP to meta.reference and complete with Authorize Transaction. See Testing transaction outcomes in sandbox.Authorizations
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. Requests made with a key that does not include the permission required by the target endpoint will be rejected with a 403 Forbidden response; an unrecognised, malformed or revoked key returns 401 Unauthorized. Manage your keys and their permissions under Developer → API keys in the dashboard.
Headers
API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable.
Body
- Withdraw
- Deposit
- Swap
Send funds to a customer's destination payment method. This is the default when type is omitted. Provide exactly one of sourceAmount or destinationAmount; sending sourceAmount alone lets the API compute the destination side at the live forward rate.
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.
"69528240ba52c13b669fb239"
The 3-letter ISO 4217 currency code of the destination currency (e.g., USD, NGN).
"USD"
The 3-letter ISO 4217 currency code of the source currency (e.g., USD, NGN).
"NGN"
Required for WITHDRAW transactions. The id of the destination payment method that money will be sent to.
"690df3281c11eea59108fcaf"
Transaction metadata. idempotencyKey and reference are required.
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.
WITHDRAW The transaction amount in the source currency. For WITHDRAW, provide exactly one of sourceAmount or destinationAmount: 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). For DEPOSIT the required amount is destinationAmount, so sourceAmount is optional. For SWAP, provide exactly one of sourceAmount or destinationAmount: setting sourceAmount makes the API compute destinationAmount at the live exchange rate.
"100.50"
The transaction amount in the destination currency. Required for DEPOSIT. For WITHDRAW, provide exactly one of sourceAmount or destinationAmount: setting destinationAmount fixes the payout amount, while omitting it and sending sourceAmount lets the API compute destinationAmount at the live forward rate. 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.
"100.50"
Required for DEPOSIT transactions. The id of the source payment method that money will be pulled from.
"690df3281c11eea59108fcaf"
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.
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.
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.
