Models - Afriex Business API

Customer

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

Transaction Types

Transaction Channels

Transaction Statuses

TransactionMeta

The meta object passed when creating a transaction. idempotencyKey and reference are required.

{
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "ORDER-12345",
    "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.

Server-set meta fields

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

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.

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

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.

Payment Channels

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

PaymentMethodRecipient

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

PaymentMethodTransaction

Optional per-transaction details attached to a payment method.

PaymentMethodInstitution

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

Error Response

All API errors return a consistent JSON body:

{
  "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