Integration Guide

This guide covers best practices for integrating the Afriex Business API into your application.

OpenAPI spec

Get the full OpenAPI spec at this endpoint for code generation, SDKs, and API tooling.

MCP server

Add the Afriex Business API to your MCP client and search the docs from Cursor, Claude Code, and other MCP-enabled tools.

Postman collection

Import every endpoint into Postman, with sandbox example requests and API key auth already set up.

Environments

The Afriex API provides two environments:

Environment	Base URL	Purpose
Sandbox	`https://sandbox.api.afriex.com`	Testing and development
Production	`https://api.afriex.com`	Live transactions

Never use production API keys in your testing environment.

Authentication

All API requests require authentication using your API key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  https://sandbox.api.afriex.com/api/v1/customer

See Authentication for permissions, IP allowlisting, and request signing.

Using Postman

The Postman collection is generated from the same OpenAPI spec as this API reference, so it always lists the current endpoints, parameters, and example requests.

Click Run in Postman to fork the collection into your own Postman workspace. Open the collection’s Variables tab, paste your sandbox API key into apiKey, and send any request. Every request sends the key in the x-api-key header, and requests go to the sandbox by default. To keep your key in an environment instead, or to switch to production, fork the Afriex Sandbox and Afriex Production environments from the Afriex Postman workspace. Each request comes with an example body. Optional query parameters are included but switched off, so tick the ones you want to use. Using the Postman desktop app? Your fork appears there automatically once you’re signed in with the same account. Or skip the browser: click Import in the app and paste the link below.

Importing by link

To import the collection instead of forking it, click Import in Postman and paste this link:

https://docs.afriex.com/api-reference/postman-collection.json

Then set apiKey to your sandbox API key in a Postman environment. Requests go to the sandbox by default; for production, also set baseUrl to https://api.afriex.com in that environment.

To pick up API changes, use Pull changes on your fork, or import the link again and choose Replace. If your API key is in an environment, it is not affected.

Amounts

Transaction amounts are decimal values in the currency’s main unit. A sourceAmount of "10" in USD is ten US dollars, not ten cents.

Send amounts as numeric strings, such as "10" or "100.50". The API also accepts numbers, but strings keep floating-point rounding out of your code.
Responses and webhooks return amounts as strings. Parse them with a decimal type, not a float.
Checkout sessions are the exception. Their amount is in minor units, such as kobo or cents. See Create checkout session.

Idempotency

Creating a transaction takes a meta.idempotencyKey and a meta.reference. Both must be unique in your business, so a retry can never create a second transaction:

{
  "customerId": "CUSTOMER_ID",
  "type": "WITHDRAW",
  "destinationAmount": "5000",
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "destinationId": "PAYMENT_METHOD_ID",
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "YOUR_REFERENCE"
  }
}

A repeat returns 409 DUPLICATE_REQUEST and creates nothing. See Idempotency for what a duplicate returns, how to recover after a timeout, and why a failed swap needs a new key.

Error Handling

Every error has the same shape: a machine-readable code to branch on, and details.friendlyMessage, which says what was wrong with this request.

{
  "code": "INVALID_BUSINESS_CUSTOMER_REQUEST",
  "error": "Invalid business customer request",
  "details": {
    "errorMessage": "Invalid business customer request",
    "friendlyMessage": "Invalid customer phone provided: PHONE_COUNTRY_MISMATCH"
  }
}

Retry 429, 500, 503, and requests that time out, with backoff. Don’t retry the other 4xx errors until you change the request. See Errors for every status and what to do about it.

Pagination

List endpoints take a zero-based page and a limit of up to 100, and return {data, total, page}:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://sandbox.api.afriex.com/api/v1/customer?page=0&limit=10"

See Pagination for the sort order of each list, how to find the last page, and how to page through a list that changes while you read it.

Webhook Integration

Set up webhooks to receive real-time event notifications:

Configure your webhook URL in the Dashboard
Verify the x-webhook-signature header (ECDSA P-384 with SHA-256, DER signature, base64) using the raw request body. The key is not RSA. See Security and signature validation
Use the webhook public key from Developer → Webhook in the Dashboard (sandbox and production keys are different)
Return 200 quickly after successful verification and processing

If signature verification fails, return 400 or 401. Afriex makes up to 12 delivery attempts, the first one and then up to 11 retries, with exponential backoff starting at 30 seconds.

Webhook Documentation

Learn more about webhook setup, security, and event types.

Rate Limiting

Be mindful of rate limits when making API calls:

Wait for Retry-After before you retry a 429, and back off on 500 and 503
Cache exchange rates and other static data
Use webhooks to learn about status changes

See Rate limits for the per-endpoint limits, the headers that show where you stand, and how to handle a 429.

Testing Your Integration

Test in sandbox

Use the sandbox environment to test all API calls without affecting live data.

Verify Webhooks

Test webhook handling with the sandbox environment events.

Go Live

Work through the go-live checklist. Besides the base URL and API key, the webhook public key and the webhook IP address change in production.

Building and testing in sandbox

For the full sandbox reference, including the test-value taxonomy, how to simulate deterministic outcomes, OTP flow, virtual-account transfers, balance topups, and webhook drills, see the Testing in Sandbox guide.

Support

Need help with your integration? Contact us at support@afriex.com.

Getting started

Core Concepts

Testing

Integration Guide