Models

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
`reference`	string	Shortened customer reference. Returned on customer reads (list and by-ID) and used as the `reference` when submitting a pool-account payment proof. Falls back to `customerId` when no shortened value has been assigned.
`name`	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`)
`meta`	object	Optional metadata you attach to the customer
`createdAt`	string (ISO 8601)	Timestamp when the customer was created
`updatedAt`	string (ISO 8601)	Timestamp of the last update

On create and update requests, supply the customer’s full name as fullName; responses return it as name. KYC details are submitted separately through the Update KYC endpoint.

Transaction

Field	Type	Description
`transactionId`	string	Unique identifier for the transaction
`customerId`	string	ID of the customer who owns this transaction
`sourceId`	string	ID of the source payment method
`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`)
`rate`	string	Realized source-to-destination exchange rate, as `1 sourceCurrency = rate destinationCurrency` (equal to `destinationAmount / sourceAmount`)
`fee`	string	Fee charged for this transaction, denominated in `sourceCurrency`. Reported separately from `sourceAmount`. Omitted when no fee applied.
`type`	string	Transaction type. See Transaction Types
`channel`	string	Payment channel of the transaction. See Transaction Channels.
`status`	string	Current status. See Transaction Statuses
`merchantReference`	string	Merchant-supplied reference (mirrors `meta.reference` from the create request)
`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
`REVERSAL`, `SCHEDULED`, `SEND`	Can appear on transactions you list or fetch. You can’t create them through the API.

You can create DEPOSIT, WITHDRAW, and SWAP. Handle the other values when you read transactions back.

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
`POOL_ACCOUNT`	Shared pool account for incoming deposits
`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. A `SWAP` uses this channel, because it moves money between your own wallets
`PAYMENT_LINQ`	A payment collected through an Afriex payment link
`ADMIN`	A manual credit or debit to your balance made by Afriex, for example a correction

You don’t send WALLET, PAYMENT_LINQ, or ADMIN. They can appear on transactions you read, so handle them when you list transactions.

Transaction Statuses

Status	Description
`PENDING`	Transaction has been received and is awaiting processing
`PROCESSING`	Transaction is actively being processed
`SUCCESS`	Transaction settled successfully
`FAILED`	Transaction failed. Check `meta.failureReason` for the reason code. See Failure reasons.
`CANCELLED`	Transaction was cancelled before processing
`REFUNDED`	Funds were returned to the sender
`RETRY`	Transaction is being automatically retried
`UNKNOWN`	Status could not be determined. Contact support.
`SCHEDULED`	Transaction is scheduled to be processed later
`CUSTOMER_ACTION_REQUIRED`	Transaction is paused pending an action from the customer
`REJECTED`	Transaction was rejected after review
`IN_REVIEW`	Transaction is held pending a review
`RFI_REQUESTED`	Transaction is held pending a request for information. Someone may contact you for more detail about the transfer.
`DISPUTED`	A dispute has been raised against the transaction
`DISPUTE_RESOLVED`	The dispute has been resolved
`DISPUTE_WON`	The dispute was resolved in your favour
`DISPUTE_LOST`	The dispute was resolved against you
`DISPUTE_EVIDENCE_SUBMITTED`	Evidence has been submitted for the dispute

IN_REVIEW and RFI_REQUESTED are review states: the transaction is still in flight and waiting on a review, not on you. Treat them as non-terminal and keep listening, rather than classifying them as failures.More generally, handle unrecognised statuses as non-terminal rather than failed. New values can be added, and existing ones do not change meaning.

Subscribe to Transaction Events to receive real-time status updates instead of polling the API.

TransactionMeta

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). Returned on the transaction as `merchantReference`.
`narration`	string	No	Human-readable reason or description for the transaction
`invoice`	string	Required for SWIFT withdrawals; otherwise No	S3 object key for the invoice document, as returned by Generate Upload URL. Upload the file to the presigned URL first, then pass the returned `key` here verbatim. The object is verified to exist in storage before the transaction is created; unknown keys are rejected.
`settlement`	string	No	Settlement handling. `spot` (default) processes immediately and debits your Payout wallet. `request` is WITHDRAW-only; it debits your Collection wallet instead and queues the payout for the next business day in the destination payment method’s country. Read that wallet’s balance with Get Balance and `walletType=DEPOSIT`. Omit `settlement` (or send `spot`) for an ordinary payout.

{
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "ORDER-12345",
    "narration": "Payment for invoice #12345",
    "invoice": "64f0c2a1e4b0a1b2c3d4e5f6/invoice.pdf"
  }
}

Always provide a unique idempotencyKey per transaction attempt. If a transaction with the same key (or the same reference) already exists or is still being processed, Afriex rejects the request with 409 DUPLICATE_REQUEST instead of creating a duplicate. Look up the original with List Transactions. A request that was rejected with 429 never created a transaction, so you can retry it with the same key. See Idempotency for how to recover after a timeout.

Server-set meta fields

Afriex also sets fields on meta after the transaction is created. These echo alongside any fields you passed on create.

Field	Type	Description
`otpRequired`	boolean	`true` when the customer must complete an OTP challenge before the transaction can settle. See Simulating OTP-required deposits.
`failureReason`	object	Present only when `status` is `FAILED` or `REJECTED`. Carries a stable `code`, a customer-safe `message`, and a `retryable` flag. See Failure reasons.

Failure reasons

When a transaction reaches FAILED or REJECTED, meta.failureReason explains why using a stable AFX_* code and a customer-safe message. Branch on code rather than the underlying rail so your integration stays stable across routing changes.

Field	Type	Description
`code`	string	Stable `AFX_*` failure code. Safe to switch on; the set grows over time but existing values do not change meaning.
`message`	string	Customer-safe short description of the failure. Suitable for display; do not parse. Branch on `code` instead.
`retryable`	boolean	`true` when re-submitting the same request (or, for `AFX_PROPOSAL_EXPIRED`, starting a fresh proposal) may succeed. `false` when the caller must change the request before retrying.

{
  "meta": {
    "failureReason": {
      "code": "AFX_VELOCITY_LIMIT_EXCEEDED",
      "message": "This transaction exceeds the allowed velocity limit. Try again later.",
      "retryable": true
    }
  }
}

Code	Meaning
`AFX_REQUEST_FAILED`	Generic failure while processing the request. Usually retryable.
`AFX_SYSTEM_ERROR`	Internal Afriex error. Retry with backoff.
`AFX_SERVICE_UNAVAILABLE`	A downstream service was unavailable. Retry with backoff.
`AFX_INVALID_CURRENCY`	The requested currency is not supported for this route.
`AFX_INVALID_AMOUNT`	The requested amount is invalid or outside allowed limits.
`AFX_INVALID_RECIPIENT`	The recipient payment method is invalid or incomplete.
`AFX_ACCOUNT_CLOSED`	The recipient account is closed.
`AFX_NAME_MISMATCH`	The beneficiary name does not match the account records.
`AFX_RECIPIENT_NOT_FOUND`	The recipient account could not be located at the destination institution.
`AFX_BENEFICIARY_RESTRICTED`	The beneficiary is restricted and cannot receive funds.
`AFX_INVALID_SENDER`	The sender’s payment method is invalid or ineligible.
`AFX_INVALID_REQUEST`	The request payload is malformed or inconsistent.
`AFX_VELOCITY_LIMIT_EXCEEDED`	The customer has exceeded a velocity limit. Retry after the window resets.
`AFX_AMOUNT_LIMIT_EXCEEDED`	The request exceeds a per-transaction, daily, or account limit.
`AFX_RECIPIENT_WALLET_LIMIT_REACHED`	The recipient’s wallet has reached a limit at the destination, so it cannot receive this payout.
`AFX_PAYMENT_FAILED`	The payment leg failed at the payment rail.
`AFX_COMPLIANCE_REJECTED`	The transaction was rejected during compliance review.
`AFX_PROPOSAL_EXPIRED`	The rate proposal expired before the transaction was committed. Start a fresh proposal.

The AFX_* set may grow over time as new failure modes are surfaced. Existing values will not change meaning. Handle unknown codes by falling back to message.

PaymentMethod

Empty fields are omitted from responses. Account-shaped channels (BANK_ACCOUNT, MOBILE_MONEY, SWIFT, etc.) populate accountName, accountNumber, and institution; the CARD channel instead populates last4, brand, expiration, and cardName.

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
`currency`	string	ISO 4217 currency code. Use this instead of inferring from `countryCode`, which is ambiguous (e.g. a USD account in a non-US country)
`capabilities`	string[]	Operations this method is enabled for (e.g. `DEPOSIT`, `WITHDRAW`). Filterable via the `capabilities` query parameter on List Payment Methods
`reference`	string	Identifier used to reconcile incoming deposits against
`accountName`	string	Account holder name. Present for account-shaped channels
`accountNumber`	string	Account number. Present for account-shaped channels
`routingNumber`	string	Bank routing number. Present for account-shaped channels that carry one (e.g. ACH bank accounts)
`bankAddress`	object	Issuing bank’s postal address. See PaymentMethodBankAddress
`institution`	object	Bank or provider details. See PaymentMethodInstitution
`recipient`	object	Recipient contact details. See PaymentMethodRecipient
`transaction`	object	Per-transaction overrides. See PaymentMethodTransaction
`status`	string	Lifecycle status. See Payment Method Statuses
`last4`	string	Last 4 digits of the card. `CARD` channel only
`brand`	string	Card brand (e.g. `Visa`, `MasterCard`). `CARD` channel only
`expiration`	object	Card expiry with `month` and `year`. `CARD` channel only
`cardName`	string	Name on the card. `CARD` channel only
`expiresInMinutes`	integer	Minutes until a dynamic virtual account expires, when applicable
`amount`	number	Requested amount for a dynamic virtual account, when applicable
`extra`	object	Additional channel-specific properties
`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
`INTERAC`	Interac e-Transfer (Canada)
`UPI`	Unified Payments Interface (India)
`WE_CHAT`	WeChat Pay
`ALIPAY`	Alipay
`CARD`	Card payment
`CRYPTO`	Crypto rail
`VIRTUAL_BANK_ACCOUNT`	Hosted virtual bank account
`POOL_ACCOUNT`	Shared pool account for incoming deposits
`ACH_BANK_ACCOUNT`	US ACH bank transfer
`PAYBILL_TILL`	Paybill / Till (M-Pesa business numbers)
`RFP`	Request for Payment
`VIRTUAL_CARD`	Virtual card

Not every channel is valid when creating a payment method. The Create Payment Method endpoint accepts a narrower set of channels; the list above covers all channels that can appear on a returned payment method.

Payment Method Statuses

Status	Description
`active`	Payment method is active and usable
`pending`	Payment method is awaiting activation or verification
`deleted`	Payment method has been deleted
`expired`	Payment method has expired (e.g. an expired card)
`blocked`	Payment method has been blocked

PaymentMethodRecipient

Recipient contact details attached to a payment method, when supplied.

Field	Type	Description
`recipientName`	string	Name of the recipient
`recipientEmail`	string (email)	Email address of the recipient
`recipientPhone`	string	Phone number of the recipient in E.164 format
`recipientAddress`	string	Address of the recipient

A payment method returns only the four fields above. These are accepted when you create one but are not returned on it:

Field	Type	Description
`recipientAddressLine1`	string	Optional. First line of `recipientAddress`. Used on SWIFT payment methods when `institutionAddressLine1` is not sent.
`recipientAddressCity`	string	Optional. City of `recipientAddress`
`recipientAddressState`	string	Optional. State of `recipientAddress`
`recipientAddressZip`	string	Optional. Postal or ZIP code of `recipientAddress`
`recipientAddressCountry`	string	Optional. Country of `recipientAddress`
`recipientIdType`	string	The type of the recipient’s ID. Needed, with `recipientIdNumber`, for `BANK_ACCOUNT` payment methods in CNY, where it is recorded as the recipient’s KYC.
`recipientIdNumber`	string	The number of the ID named by `recipientIdType`. Needed for `BANK_ACCOUNT` payment methods in CNY.
`recipientUpiId`	string	The recipient’s UPI ID, used on UPI payment methods. When omitted, `accountNumber` is used.

PaymentMethodTransaction

Optional per-transaction details attached to a payment method.

Field	Type	Description
`transactionNarration`	string	Optional reason or description for the transaction
`transactionInvoice`	string	S3 object key for the invoice document, as returned by Generate Upload URL

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
`correspondentBankName`	string	Correspondent (intermediary) bank name. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices.
`correspondentBankAccountNumber`	string	Correspondent (intermediary) bank account number. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices.

A payment method returns only the fields above. These are accepted when you create one but are not returned on it:

Field	Type	Description
`institutionAddressLine1`	string	Optional. First line of `institutionAddress`, for SWIFT payment methods. Used ahead of `recipientAddressLine1`.
`institutionAddressCity`	string	Optional. City of `institutionAddress`, for SWIFT payment methods
`institutionAddressState`	string	Optional. State of `institutionAddress`, for SWIFT payment methods
`institutionAddressZip`	string	Optional. Postal or ZIP code of `institutionAddress`, for SWIFT payment methods
`institutionAddressCountry`	string	Optional. Country of `institutionAddress`, for SWIFT payment methods
`institutionBranch`	string	The branch of the bank. Required when you create a `BANK_ACCOUNT` payment method in CNY. The institution list returns it too, often as an empty string.

Use the List Institutions endpoint to retrieve valid institutions for a given country and channel.

PaymentMethodBankAddress

The postal address of the issuing bank, not the account holder. Populated per account by the provider that provisioned it, so it is present on virtual accounts and other account-shaped payment methods whose provider supplies it, and omitted otherwise.

Field	Type	Description
`line1`	string	First line of the bank’s street address
`line2`	string	Second line of the bank’s street address, when present
`city`	string	City
`state`	string	State or region, when present
`zip`	string	Postal or ZIP code
`country`	string	Country, as supplied by the provider

This is the address to quote as the beneficiary bank when originating an international wire into a virtual account.

On Create Transaction, correspondentBankName and correspondentBankAccountNumber can also be passed at the top level as a fallback when the destination payment method lacks them (USD WITHDRAW with meta.settlement: "request"). The values stored on the payment method take precedence; the two fields must be supplied together.

PaymentBatch

A saved group of payout recipients funded from one wallet. Add recipients over time, then trigger the payouts in one call with Withdraw Batch. Each execution is recorded as a session.

Field	Type	Description
`id`	string	Unique identifier for the batch
`name`	string	Label for the batch
`sourcePaymentMethod`	object	The wallet the batch is funded from, with its `channel` and `currencyCode`. Every payout in the batch is converted from this currency.

The list endpoint returns a lighter shape (id, name, meta) without the full sourcePaymentMethod; call Get Payment Batch for the full record.

PaymentBatchRecipient

A recipient inside a batch: a payout target with a fixed amount for each run.

Field	Type	Description
`recipientId`	string	The recipient’s id within this batch. Use this to update or remove the recipient.
`paymentMethodId`	string	The saved payment method backing this recipient (list responses populate this; add/update return the same value in `id`).
`channel`	string	Payment channel. See Payment Channels.
`countryCode`	string	ISO 3166-1 alpha-2 country code
`accountName`	string	Account holder name
`accountNumber`	string	Account number
`institution`	object	Bank / provider details. See PaymentMethodInstitution.
`amount`	object	Per-recipient payout amount for every run of the batch: `value`, a numeric string such as `"15000"`, and `currencyCode`, such as `"NGN"`

PaymentBatchSession

A single execution of Withdraw Batch. Each session records the recipient outcomes for that run.

Field	Type	Description
`id`	string	Session (run) id
`batchId`	string	The batch this run belongs to
`createdAt`	string (ISO 8601)	When the run was started
`meta`	object	Per-run metadata, including outcomes

Bulk operations (bulk add recipients, withdraw) return a PaymentBatchOutcomes shape with successes and errors keyed by account number: each entry is either the created object or the reason it failed. Use this to reconcile which items landed.

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
`details.data`	object	Optional caller-safe context. On a customer-create uniqueness conflict (`EMAIL_ALREADY_EXISTS`, `PHONE_NUMBER_ALREADY_EXISTS`) contains `{ customerId }` for the existing customer so you can adopt it without a follow-up lookup

{
  "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. `details.friendlyMessage` says which field, for example `Invalid customer phone provided: PHONE_COUNTRY_MISMATCH` when the phone number doesn’t match `countryCode`
`EMAIL_ALREADY_EXISTS`	409	A customer with this email already exists. `details.data.customerId` returns the existing customer’s id.
`PHONE_NUMBER_ALREADY_EXISTS`	409	A customer with this phone number already exists. `details.data.customerId` returns the existing customer’s id.
`DUPLICATE_REQUEST`	409	A transaction with the same `meta.idempotencyKey` or `meta.reference` already exists or is being processed. See Idempotency
`BUSINESS_CUSTOMER_NOT_FOUND`	404	No customer with that id belongs to your business
`BUSINESS_PAYMENT_METHOD_NOT_FOUND`	404	No payment method with that id belongs to your business. Get Pool Account also returns it when your business has no pool account in the country you asked for
`BALANCE_INSUFFICIENT`	402	Your wallet balance is too low to cover the transaction. Fund the wallet and send the request again
`BUSINESS_LIMIT_EXCEEDED`	403	The transaction would take your business over one of its limits. `details.friendlyMessage` names the limit and the period. See Business limits
`BUSINESS_TRANSACTION_MIN_AMOUNT_NOT_MET`	400	The transaction is below the smallest amount one of your business limits allows. See Business limits
`COUNTRY_NOT_SUPPORTED`	422	The destination country is not currently available
`PAYMENT_METHOD_CURRENCY_MISMATCH`	422	The payment method’s currency does not match `destinationCurrency`
`VIRTUAL_ACCOUNT_LIMIT_REACHED`	403	The per-(business, customer, currency) virtual account limit is reached
`VIRTUAL_ACCOUNT_BVN_REQUIRED`	400	A permanent `NGN` virtual account needs a BVN and the holder has none. See Create Virtual Account
`UNSUPPORTED_VIRTUAL_ACCOUNT_CURRENCY`	422	The currency cannot be held by the account holder you asked for, for example a customer asking for `KES`
`UNSUPPORTED_VIRTUAL_ACCOUNT_TYPE`	422	The currency does not offer the account type you asked for, permanent (`label`) or one-time (`amount`)
`BUSINESS_TRANSACTION_NOT_FOUND`	404	No transaction with that id belongs to your business
`VALIDATION_ERROR`	422	Request failed schema validation. `details.friendlyMessage` names the offending field
`RATE_LIMIT_ERROR`	429	Too many requests. Wait the number of seconds in the `Retry-After` header when it is present, then retry. See Rate limits
`INTERNAL_SERVER_ERROR`	500	Unexpected server error. Safe to retry idempotent requests with backoff
`SERVICE_UNAVAILABLE`	503	An upstream processor failed or timed out, or the API is momentarily offline. Retry with backoff and honour `Retry-After` when present

There is no generic NOT_FOUND code. Missing resources return a specific code naming the resource, as above.

Overview

Requests and responses

Balance

Checkout Sessions

Rates

Customers

Payment Methods

Media

Transactions

Payment Batches

SME Registration

Sandbox helpers

Webhooks

Customer

Transaction

Transaction Types

Transaction Channels

Transaction Statuses

TransactionMeta

Server-set meta fields

Failure reasons

PaymentMethod

Payment Channels

Payment Method Statuses

PaymentMethodRecipient

PaymentMethodTransaction

PaymentMethodInstitution

PaymentMethodBankAddress

PaymentBatch

PaymentBatchRecipient

PaymentBatchSession

Error Response

Common error codes

​Customer

​Transaction

​Transaction Types

​Transaction Channels

​Transaction Statuses

​TransactionMeta

​Server-set meta fields

​Failure reasons

​PaymentMethod

​Payment Channels

​Payment Method Statuses

​PaymentMethodRecipient

​PaymentMethodTransaction

​PaymentMethodInstitution

​PaymentMethodBankAddress

​PaymentBatch

​PaymentBatchRecipient

​PaymentBatchSession

​Error Response

​Common error codes

Customer

Transaction

Transaction Types

Transaction Channels

Transaction Statuses

TransactionMeta

Server-set meta fields

Failure reasons

PaymentMethod

Payment Channels

Payment Method Statuses

PaymentMethodRecipient

PaymentMethodTransaction

PaymentMethodInstitution

PaymentMethodBankAddress

PaymentBatch

PaymentBatchRecipient

PaymentBatchSession

Error Response

Common error codes