Quickstart

This guide takes you from a new API key to a settled payout in the sandbox. You create a customer, save the bank account you are paying, fund your sandbox balance, price the payout, and send it. No real money moves.

Want to see what the hosted checkout looks like before writing any code? Try the sandbox demo. No API key required.

Prerequisites

An Afriex Business account (sign up here)
A tool for making HTTP requests (cURL, Postman, or your preferred HTTP client)

Every request below goes to the sandbox at https://sandbox.api.afriex.com. Replace YOUR_API_KEY with your sandbox key, and replace the IDs in capitals with the values your earlier calls returned.

Get a sandbox API key

Log in to the Afriex Dashboard and switch the Test / Live toggle to Test.
Go to Developer and open the API Keys tab.
Generate a key. For this guide, give it Write on Customers, Payment methods, and Withdrawals, and Read on Rates and quotes and Transactions. See Permissions for what each level grants.
Copy the key and store it securely.

Keep your API key on your server. Never put it in client-side code or a public repository. Test mode keys only work against the sandbox, and live mode keys only work against production.

Create a customer

A customer is the end user you are acting for. On a payout, the customer is the sender; you save the recipient’s bank account in the next step.

curl -X POST https://sandbox.api.afriex.com/api/v1/customer \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  }'

The response returns the new customer. Keep its customerId for the next steps.

{
  "data": {
    "customerId": "69516dd0464b2213bd74cfad",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  }
}

You send the customer’s name as fullName, and responses return it as name.

Save the recipient's bank account

A payout goes to a payment method, so save the recipient’s bank account first, linked to the customer. Look up the bank’s institutionCode with List Institutions rather than hardcoding it:

curl "https://sandbox.api.afriex.com/api/v1/payment-method/institution?countryCode=NG&channel=BANK_ACCOUNT" \
  -H "x-api-key: YOUR_API_KEY"

Then create the payment method with an institutionCode and institutionName from that list:

curl -X POST https://sandbox.api.afriex.com/api/v1/payment-method \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "accountName": "Amaka Okafor",
    "accountNumber": "0123456789",
    "countryCode": "NG",
    "institution": {
      "institutionCode": "000013",
      "institutionName": "Guaranty Trust Bank (GTBank) Plc"
    }
  }'

Keep the paymentMethodId from the response.

In the sandbox, the last four digits of the account number choose what happens to payouts to it. 6789 succeeds. 0001 fails, and 0003 stays pending until you call /simulate. See Testing in Sandbox for every test value.

Fund your sandbox balance

A payout debits your Payout wallet, so give it some test USD with Top Up Sandbox Balance:

curl -X POST https://sandbox.api.afriex.com/api/v1/org/balance/topup \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "amount": 500, "currency": "USD" }'

This endpoint is sandbox only and returns 403 in production.

Price the payout

Ask for a quote before you send. Choose the side you want to be exact. Here the recipient gets exactly 5,000 NGN, and the API works out how many USD that costs:

curl "https://sandbox.api.afriex.com/api/v1/transaction/quote?customerId=CUSTOMER_ID&destinationId=PAYMENT_METHOD_ID&sourceCurrency=USD&destinationCurrency=NGN&destinationAmount=5000" \
  -H "x-api-key: YOUR_API_KEY"

The response holds the rate, any fee, and both amounts. A quote creates nothing, and creating the transaction with the same inputs charges the quoted amounts.

Send the payout

Create a WITHDRAW with the same inputs as the quote. Send only the amount you fixed, here destinationAmount, and let the API derive the other side.

curl -X POST https://sandbox.api.afriex.com/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "type": "WITHDRAW",
    "destinationAmount": "5000",
    "sourceCurrency": "USD",
    "destinationCurrency": "NGN",
    "destinationId": "PAYMENT_METHOD_ID",
    "meta": {
      "reference": "order-12345",
      "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

meta.reference is your own order ID, and meta.idempotencyKey is a fresh UUID for this attempt. Both must be unique in your business. If the request times out, retry with the same idempotency key so it can never create a second payout. See Idempotency.

Check the result

The transaction starts as PENDING. In the sandbox it settles about 5 minutes later. Add SIMULATE_INSTANT anywhere in meta.reference to settle it in about 30 seconds.Look it up by your reference:

curl "https://sandbox.api.afriex.com/api/v1/transaction?reference=order-12345" \
  -H "x-api-key: YOUR_API_KEY"

In a real integration, don’t poll. Listen for the TRANSACTION.UPDATED webhook and act on its status.

Next steps

Planning to use webhooks? Allowlist these Afriex IP addresses on your server so webhook deliveries are not blocked:

Environment	IP address
Sandbox	`34.234.189.210`
Production	`34.197.33.100`

See Webhook setup for full details.

Connecting the pieces

How customers, payment methods, and transactions fit together, with payloads for every transaction type.

Testing in Sandbox

Drive failures, OTPs, pending payouts, and webhooks before you go live.

Webhooks

Receive real-time notifications and verify their signatures.

API Reference

Explore all available endpoints and their parameters.

Step-by-step tutorial

Prefer a tutorial? Follow the blog walkthrough from signup to your first request.

Support

Need help? Contact us at support@afriex.com.

Getting started

Core Concepts

Testing

Prerequisites

Next steps

Connecting the pieces

Testing in Sandbox

Webhooks

API Reference

Step-by-step tutorial

Support

​Prerequisites

​Next steps

Connecting the pieces

Testing in Sandbox

Webhooks

API Reference

Step-by-step tutorial

​Support

Prerequisites

Next steps

Support