Skip to main content
POST
/
api
/
v1
/
transaction
curl --request POST \
  --url https://sandbox.api.afriex.com/api/v1/transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerId": "69528240ba52c13b669fb239",
  "type": "WITHDRAW",
  "sourceAmount": "10",
  "destinationAmount": 5000,
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "destinationId": "690df3281c11eea59108fcaf",
  "meta": {
    "reference": "ref-withdraw-001",
    "idempotencyKey": "idem-withdraw-001"
  }
}
'
{
  "data": {
    "status": "PENDING",
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "sourceAmount": "3.28847",
    "sourceCurrency": "USD",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "destinationId": "690df3281c11eea59108fcaf",
    "customerId": "69528240ba52c13b669fb239",
    "transactionId": "69d60071ab82306f11b03393",
    "meta": {
      "reference": "ref-withdraw-001",
      "idempotencyKey": "idem-withdraw-001"
    },
    "createdAt": "2026-04-08T07:14:57.444Z",
    "updatedAt": "2026-04-08T07:14:57.444Z"
  }
}
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. 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.
Testing in sandbox? Sandbox transactions settle automatically within ~1-2 minutes and send the TRANSACTION.UPDATED webhook. Set meta.reference to a value containing fail to test a FAILED outcome, or any other value for SUCCESS. See Testing transaction outcomes 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. 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

​
x-api-version
string

API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable.

Body

application/json

Send funds to a customer's destination payment method. This is the default when type is omitted.

​
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"

​
destinationAmount
required

The transaction amount in the destination currency. Required for DEPOSIT and WITHDRAW. 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.

Example:

"100.50"

​
destinationCurrency
string
required

The 3-letter ISO 4217 currency code of the destination currency (e.g., USD, NGN).

Example:

"USD"

​
sourceCurrency
string
required

The 3-letter ISO 4217 currency code of the source currency (e.g., USD, NGN).

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 DEPOSIT and WITHDRAW 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.

Example:

"100.50"

​
sourceId
string

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

Example:

"690df3281c11eea59108fcaf"

Response

Transaction created successfully.

​
data
object