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 |
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 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. |
