Documentation Index
Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
Use this file to discover all available pages before exploring further.
This page documents the key data models returned and accepted by the API, including all enumerated values and field-level details.
Customer
| Field | Type | Description |
|---|
customerId | string | Unique identifier for the customer |
fullName | string | Full name of the customer |
email | string (email) | Email address |
phone | string | Phone number in E.164 format (e.g. +2348192837465) |
countryCode | string | ISO 3166-1 alpha-2 country code (e.g. NG) |
kyc | object | Optional KYC document details |
meta | object | Optional metadata you attach to the customer |
Transaction
| Field | Type | Description |
|---|
transactionId | string | Unique identifier for the transaction |
customerId | string | ID of the customer who owns this transaction |
destinationId | string | ID of the destination payment method |
sourceAmount | string | Amount debited from the source wallet |
sourceCurrency | string | ISO 4217 currency code of the source wallet (e.g. USD) |
destinationAmount | string | Amount credited to the destination |
destinationCurrency | string | ISO 4217 currency code of the destination (e.g. NGN) |
type | string | Transaction type. See Transaction Types |
channel | string | Payment channel of the transaction. See Transaction Channels. |
status | string | Current status. See Transaction Statuses |
meta | object | Metadata attached to the transaction. See TransactionMeta |
createdAt | string (ISO 8601) | Timestamp when the transaction was created |
updatedAt | string (ISO 8601) | Timestamp of the last update |
Transaction Types
| Value | Description |
|---|
WITHDRAW | Send funds from the Afriex wallet to a recipient’s payment method |
DEPOSIT | Receive funds into the Afriex wallet |
SWAP | Convert funds between currencies within the Afriex wallet |
Transaction Channels
| Channel | Description |
|---|
BANK_ACCOUNT | Local bank account transfer |
SWIFT | International SWIFT wire transfer |
MOBILE_MONEY | Mobile money wallet (e.g. M-Pesa, MTN MoMo) |
UPI | Unified Payments Interface (India) |
INTERAC | Interac e-Transfer (Canada) |
WE_CHAT | WeChat Pay |
CARD | Card payment |
CRYPTO | Crypto rail |
VIRTUAL_BANK_ACCOUNT | Hosted virtual bank account |
ACH_BANK_ACCOUNT | US ACH bank transfer |
PAYBILL_TILL | Paybill / Till (M-Pesa business numbers) |
RFP | Request for Payment |
VIRTUAL_CARD | Virtual card |
ALIPAY | Alipay |
WALLET | Afriex wallet (internal leg) |
Transaction Statuses
| Status | Description |
|---|
PENDING | Transaction has been received and is awaiting processing |
PROCESSING | Transaction is actively being processed |
COMPLETED | Transaction completed successfully |
SUCCESS | Alias for a successfully settled transaction |
FAILED | Transaction failed. Check the meta for details. |
CANCELLED | Transaction was cancelled before processing |
REFUNDED | Funds were returned to the sender |
IN_REVIEW | Transaction is under manual review |
REJECTED | Transaction was rejected after review |
RETRY | Transaction is being automatically retried |
UNKNOWN | Status could not be determined. Contact support. |
Subscribe to Transaction Events to receive real-time status updates instead of polling the API.
The meta object passed when creating a transaction. idempotencyKey and reference are required.
| Field | Type | Required | Description |
|---|
idempotencyKey | string | Yes | Unique key to prevent duplicate transactions. Use a UUID or your own unique identifier. |
reference | string | Yes | Your internal reference for the transaction (e.g. order ID) |
merchantId | string | No | Your merchant or business identifier, used for reconciliation |
narration | string | No | Human-readable reason or description for the transaction |
invoice | string | No | Base64-encoded invoice document to attach to the transaction |
{
"meta": {
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ORDER-12345",
"merchantId": "MERCHANT-001",
"narration": "Payment for invoice #12345",
"invoice": "base64EncodedStringHere"
}
}
Always provide a unique idempotencyKey per transaction attempt. If you retry a failed request with the same key, Afriex will return the original transaction instead of creating a duplicate.
PaymentMethod
| Field | Type | Description |
|---|
paymentMethodId | string | Unique identifier for the payment method |
customerId | string | ID of the customer who owns this payment method |
channel | string | Payment channel. See Payment Channels |
countryCode | string | ISO 3166-1 alpha-2 country code |
accountName | string | Name of the account holder |
accountNumber | string | Account number or phone number |
institution | object | Bank or provider details. See PaymentMethodInstitution |
meta | object | Optional metadata attached to the payment method |
Payment Channels
| Channel | Description |
|---|
BANK_ACCOUNT | Local bank account transfer |
MOBILE_MONEY | Mobile money wallet (e.g. M-Pesa, MTN MoMo) |
SWIFT | International SWIFT wire transfer |
UPI | Unified Payments Interface (India) |
INTERAC | Interac e-Transfer (Canada) |
WE_CHAT | WeChat Pay |
PaymentMethodInstitution
| Field | Type | Description |
|---|
institutionId | string | Unique ID of the bank or mobile money provider |
institutionName | string | Display name of the institution |
institutionCode | string | Institution code (e.g. bank code) |
institutionAddress | string | Physical address of the institution, if required |
Error Response
All API errors return a consistent JSON body:
| Field | Type | Description |
|---|
code | string | Machine-readable error code (e.g. AUTHENTICATION_ERROR) |
error | string | Short error category (e.g. Bad Request) |
details.errorMessage | string | Specific error reason (e.g. PHONE_COUNTRY_MISMATCH) |
details.friendlyMessage | string | User-friendly message you can display to end users |
{
"code": "INVALID_BUSINESS_CUSTOMER_REQUEST",
"error": "Bad Request",
"details": {
"errorMessage": "PHONE_COUNTRY_MISMATCH",
"friendlyMessage": "The phone number does not match the customer's country."
}
}
Common error codes
| Code | HTTP Status | Description |
|---|
AUTHENTICATION_ERROR | 401 | API key is missing or invalid |
INVALID_BUSINESS_CUSTOMER_REQUEST | 400 | Customer request validation failed |
PHONE_COUNTRY_MISMATCH | 400 | Phone number country does not match countryCode |
NOT_FOUND | 404 | The requested resource does not exist |
RATE_LIMIT_EXCEEDED | 429 | Too many requests. Slow down and retry with backoff. |
