Every API here is available over the APIs.io API and to AI agents over MCP.
{"openapi":"3.1.0","info":{"title":"Afriex Business API","version":"1.0.13","description":"Welcome to the Afriex Business API. This API allows you to manage customers, process payments, handle payouts, and receive real-time notifications via webhooks.\n\nFor detailed guidance on authentication, pagination, error handling, and webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in the top bar. The guide provides a step-by-step instructions to help you integrate seamlessly.","termsOfService":"https://www.afriex.com/terms-and-condition","contact":{"name":"Afriex API Support","email":"support@afriex.com","url":"https://docs.afriex.com"},"license":{"name":"Proprietary","url":"https://www.afriex.com/terms-and-condition"}},"servers":[{"url":"https://sandbox.api.afriex.com","description":"Staging Base URL"},{"url":"https://api.afriex.com","description":"Production Base URL"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Static business API key issued from the dashboard. A business can provision **multiple API keys**, each scoped to a configurable set of **permissions** (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Requests made with a key that does not include the permission required by the target endpoint is rejected with a `401 Unauthorized` response, the same response an unrecognised, malformed or revoked key returns. The API does not distinguish the two cases on the wire. Manage your keys and their permissions under **Developer → API keys** in the dashboard."}},"parameters":{"x-api-version":{"name":"x-api-version","in":"header","required":false,"description":"API version in ISO 8601 format. The only supported version is `2026-05-18`, which is also the default when the header is omitted. Any other value is rejected with a `400 Bad Request`.","schema":{"type":"string"}},"x-api-signature":{"name":"x-api-signature","in":"header","required":false,"description":"Signature of the request payload, used for request authentication where payload signing is enabled for your business.","schema":{"type":"string"}}},"schemas":{"BankCodeResolverResponse":{"type":["object","null"],"properties":{"bankName":{"type":"string","description":"The resolved bank or institution name."}}},"Customer":{"type":"object","properties":{"customerId":{"type":"string","description":"The unique identifier for the customer."},"reference":{"type":"string","description":"A shortened reference for the customer. Returned on customer reads (list and by-ID) and used as the pool-account reference when submitting a payment proof. Falls back to the customer id when no shortened reference has been assigned."},"name":{"type":"string","description":"The full name of the customer."},"email":{"type":"string","format":"email","description":"The email of the customer."},"phone":{"type":"string","description":"The phone number of the customer in E.164 format."},"countryCode":{"type":"string","description":"The country code of the customer in ISO 3166-1 alpha-2 format."},"meta":{"type":"object","description":"optional meta data you can attach to the customer."},"createdAt":{"type":"string","description":"The date and time the customer was created."},"updatedAt":{"type":"string","description":"The date and time the customer was last updated."}}},"Transaction":{"type":"object","properties":{"transactionId":{"type":"string","description":"The unique identifier for the transaction."},"customerId":{"type":"string","description":"The unique identifier of the customer."},"sourceId":{"type":"string","description":"The unique identifier of the source payment method."},"destinationId":{"type":"string","description":"The unique identifier of the destination payment method."},"sourceAmount":{"type":"string","description":"The souce transaction amount value"},"sourceCurrency":{"type":"string","description":"The currency code of the wallet charged."},"destinationAmount":{"type":"string","description":"The destination transaction amount value"},"destinationCurrency":{"type":"string","description":"The description currency code."},"type":{"type":"string","enum":["DEPOSIT","WITHDRAW","SWAP"],"description":"The type of transaction."},"channel":{"type":"string","enum":["BANK_ACCOUNT","SWIFT","MOBILE_MONEY","UPI","INTERAC","WE_CHAT","CARD","CRYPTO","VIRTUAL_BANK_ACCOUNT","POOL_ACCOUNT","ACH_BANK_ACCOUNT","PAYBILL_TILL","RFP","VIRTUAL_CARD","ALIPAY","WALLET"],"description":"The payment channel of the transaction."},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REFUNDED","RETRY","UNKNOWN","SCHEDULED","CUSTOMER_ACTION_REQUIRED","REJECTED","IN_REVIEW","CHECKER_APPROVAL_REQUIRED","ENGINEERING_REVIEW_REQUIRED","RFI_REQUESTED","DISPUTED","DISPUTE_RESOLVED","DISPUTE_WON","DISPUTE_LOST","DISPUTE_EVIDENCE_SUBMITTED"],"description":"The current status of the transaction.\n\n`CHECKER_APPROVAL_REQUIRED`, `ENGINEERING_REVIEW_REQUIRED` and `RFI_REQUESTED` are review states: the transaction is still in flight and is waiting on an internal check, not on you. Treat them as non-terminal and keep polling or listening for `TRANSACTION.UPDATED`. `RFI_REQUESTED` may result in someone contacting you for more information about the transfer."},"merchantReference":{"type":"string","description":"The merchant-supplied reference for the transaction (mirrors meta.reference from the create request)."},"rate":{"type":"string","description":"The realized source-to-destination exchange rate for the transaction, expressed as `1 sourceCurrency = rate destinationCurrency` (equal to destinationAmount / sourceAmount)."},"fee":{"type":"string","description":"The fee charged for this transaction, denominated in `sourceCurrency`. It is reported separately from `sourceAmount`. Omitted when no fee applied to the transaction."},"meta":{"type":"object","description":"Transaction metadata. Echoes the metadata you attached on create and may include server-set state flags such as `otpRequired` and `failureReason`.","properties":{"narration":{"type":"string","description":"The narration you attached when creating the transaction, echoed back. An empty string when none was provided."},"otpRequired":{"type":"boolean","description":"Returned on deposits that may need an extra authorization step. When `true`, the deposit is waiting for the customer to submit a one-time password; call `POST /transaction/{transactionId}/authorize` to complete it."},"failureReason":{"type":"object","description":"Present only when `status` is `FAILED` or `REJECTED`. Carries 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.","required":["code","message","retryable"],"properties":{"code":{"type":"string","description":"Stable `AFX_*` failure code. Safe to switch on; the set grows over time but existing values do not change meaning.","example":"AFX_VELOCITY_LIMIT_EXCEEDED","enum":["AFX_REQUEST_FAILED","AFX_SYSTEM_ERROR","AFX_SERVICE_UNAVAILABLE","AFX_INVALID_CURRENCY","AFX_INVALID_AMOUNT","AFX_INVALID_RECIPIENT","AFX_RECIPIENT_NOT_FOUND","AFX_ACCOUNT_CLOSED","AFX_NAME_MISMATCH","AFX_BENEFICIARY_RESTRICTED","AFX_INVALID_SENDER","AFX_INVALID_REQUEST","AFX_VELOCITY_LIMIT_EXCEEDED","AFX_AMOUNT_LIMIT_EXCEEDED","AFX_PAYMENT_FAILED","AFX_COMPLIANCE_REJECTED","AFX_PROPOSAL_EXPIRED"]},"message":{"type":"string","description":"Customer-safe short description of the failure. Suitable for display; do not parse — branch on `code` instead."},"retryable":{"type":"boolean","description":"`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."}}}},"additionalProperties":true},"createdAt":{"type":"string","description":"The date and time the transaction was created."},"updatedAt":{"type":"string","description":"The date and time the transaction was last updated."}}},"TransactionMeta":{"type":"object","properties":{"narration":{"type":"string","description":"The optional reason for the transaction."},"invoice":{"type":"string","description":"The invoice filename (S3 object key) for the transaction, as returned by the media upload endpoint. Required for SWIFT withdrawals: the referenced object is verified to exist in storage before the transaction is created, so upload the file first and pass the returned key verbatim."},"idempotencyKey":{"type":"string","description":"The idempotency key for the transaction."},"reference":{"type":"string","description":"The reference for the transaction."},"settlement":{"type":"string","enum":["spot","request"],"description":"Optional settlement handling for the transaction. `spot` (the default) processes immediately and debits your Payout wallet. `request` is only supported for WITHDRAW transactions: it debits your Collection wallet (rather than the default Payout wallet) and queues the payout for the next business day in the destination payment method's country. Omit `settlement` (or send `spot`) for an ordinary payout from the Payout wallet."}},"required":["idempotencyKey","reference"]},"PaymentMethodBankAddress":{"type":"object","description":"The issuing bank's postal address, populated per account by the provider that provisioned it. Present on virtual accounts and other account-shaped payment methods whose provider supplies it; omitted otherwise. This is the bank's address, not the account holder's.","properties":{"line1":{"type":"string","description":"First line of the bank's street address."},"line2":{"type":"string","description":"Second line of the bank's street address, when present."},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State or region, when present."},"zip":{"type":"string","description":"Postal or ZIP code."},"country":{"type":"string","description":"Country, as supplied by the provider."}}},"PaymentMethod":{"type":"object","description":"A payment method. Empty fields are omitted. Account-shaped channels (BANK_ACCOUNT, MOBILE_MONEY, SWIFT, etc.) populate accountName, accountNumber, and institution; the CARD channel instead populates last4, brand, expiration, and cardName.","properties":{"paymentMethodId":{"type":"string","description":"The unique identifier for the payment method."},"customerId":{"$ref":"#/components/schemas/customerId"},"reference":{"type":"string","description":"Identifier to reconcile incoming deposits against."},"institution":{"$ref":"#/components/schemas/PaymentMethodInstitution"},"transaction":{"$ref":"#/components/schemas/PaymentMethodTransaction"},"recipient":{"$ref":"#/components/schemas/PaymentMethodRecipient"},"channel":{"type":"string","enum":["BANK_ACCOUNT","MOBILE_MONEY","SWIFT","INTERAC","UPI","WE_CHAT","ALIPAY","CARD","CRYPTO","VIRTUAL_BANK_ACCOUNT","POOL_ACCOUNT","ACH_BANK_ACCOUNT","PAYBILL_TILL","RFP","VIRTUAL_CARD"],"description":"The payment method channel."},"countryCode":{"type":"string","description":"The ISO 3166-1 alpha-2 country code."},"currency":{"type":"string","description":"The payment method's currency (ISO 4217). Use this instead of inferring currency from countryCode, which is ambiguous (e.g. a USD account in a non-US country)."},"capabilities":{"type":"array","items":{"type":"string"},"description":"The operations this payment method is enabled for (e.g. DEPOSIT, WITHDRAW). Use it to select deposit-capable vs withdraw-capable methods. Also filterable via the `capabilities` query parameter."},"accountName":{"type":"string","description":"Name of the account holder. Present for account-shaped channels."},"accountNumber":{"type":"string","description":"Account number. Present for account-shaped channels."},"routingNumber":{"type":"string","description":"Bank routing number. Present for account-shaped channels that carry one (e.g. ACH bank accounts)."},"bankAddress":{"$ref":"#/components/schemas/PaymentMethodBankAddress"},"status":{"type":"string","enum":["active","pending","deleted","expired","blocked"],"description":"Lifecycle status of the payment method."},"last4":{"type":"string","description":"Last 4 digits of the card. CARD channel only."},"brand":{"type":"string","enum":["Visa","MasterCard","Discover","American Express","JCB","Diners Club","Eftpos Australia","UnionPay","Unknown"],"description":"Card brand. CARD channel only."},"expiration":{"type":"object","description":"Card expiration. CARD channel only.","properties":{"month":{"type":"integer"},"year":{"type":"integer"}}},"cardName":{"type":"string","description":"Name on the card. CARD channel only."},"expiresInMinutes":{"type":"integer","description":"Minutes until a dynamic virtual account expires, when applicable."},"amount":{"type":"number","description":"Requested amount for a dynamic virtual account, when applicable."},"extra":{"type":"object","description":"Additional channel-specific properties.","additionalProperties":true},"meta":{"type":"object","description":"Optional meta data you attached to the payment method."}}},"PaymentMethodInstitution":{"type":"object","properties":{"institutionId":{"type":"string","description":"The unique identifier of the bank or mobile money provider if required."},"institutionName":{"type":"string","description":"The name of the bank or mobile money provider if required."},"institutionCode":{"type":"string","description":"The code of the bank or mobile money provider."},"institutionAddress":{"type":"string","description":"The address of the bank or mobile money provider if required."},"correspondentBankName":{"type":"string","description":"The correspondent (intermediary) bank name. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices."},"correspondentBankAccountNumber":{"type":"string","description":"The correspondent (intermediary) bank account number. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices."}}},"PaymentMethodRecipient":{"type":"object","properties":{"recipientEmail":{"type":"string","format":"email","description":"The email address of the recipient if needed."},"recipientPhone":{"type":"string","description":"The phone number of the recipient in E.164 format."},"recipientAddress":{"type":"string","description":"The address of the recipient if needed."},"recipientName":{"type":"string","description":"The name of the recipient if needed."}}},"PaymentMethodTransaction":{"type":"object","properties":{"transactionInvoice":{"type":"string","description":"The invoice filename (S3 object key) for the transaction, as returned by the media upload endpoint."},"transactionNarration":{"type":"string","description":"The optional reason for the transaction."}}},"customerId":{"type":"string","description":"The unique identifier of the customer."},"amount":{"description":"A monetary amount. Accepts a number or a numeric string; responses return amounts as strings.","oneOf":[{"type":"number"},{"type":"string"}],"examples":["100.50"]},"ErrorDetails":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Detailed/technical error message."},"friendlyMessage":{"type":"string","description":"User-facing error message safe to display."},"data":{"type":"object","description":"Optional caller-safe context for the error. On a customer-create uniqueness conflict (EMAIL_ALREADY_EXISTS / PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's id, so you can adopt it without a follow-up lookup.","properties":{"customerId":{"type":"string","description":"Id of the existing customer (on a create conflict)."}}}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code."},"error":{"type":"string","description":"Human-readable error message."},"details":{"$ref":"#/components/schemas/ErrorDetails"}}},"CheckoutSessionCustomer":{"type":"object","required":["name","email","phone","countryCode"],"properties":{"name":{"type":"string","description":"The full name of the customer.","examples":["John Doe"]},"email":{"type":"string","format":"email","description":"The email address of the customer.","examples":["john.doe@example.com"]},"phone":{"type":"string","description":"The phone number of the customer in E.164 format.","examples":["+2348192837465"]},"countryCode":{"type":"string","description":"The ISO 3166-1 alpha-2 country code of the customer (e.g., 'NG', 'GH'). Case-insensitive; values are normalized to uppercase.","examples":["NG"]}}},"CreateCheckoutSessionResponse":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri","description":"The URL the customer should be redirected to in order to complete the hosted checkout flow.","examples":["https://pay.afriex.com/pay/eyJhbGciOiJI..."]},"channels":{"type":"array","description":"The payment channels the customer will actually be offered on the checkout page: the request's `channels`, in the order you sent them, minus any the currency cannot collect on. Never empty.","items":{"type":"string","enum":["VIRTUAL_BANK_ACCOUNT","MOBILE_MONEY","CARD"]},"examples":[["MOBILE_MONEY"]]}}},"PaymentMethodResolveResponse":{"type":"object","properties":{"recipientName":{"type":"string","description":"The resolved name on the account."},"institutionName":{"type":"string","description":"The name of the resolved bank or mobile money provider."},"institutionCode":{"type":"string","description":"The code of the resolved bank or mobile money provider."}}},"PoolAccountPaymentProofSenderDetails":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The sender's full name."},"accountNumber":{"type":"string","description":"The sender's account number or wallet identifier."},"bankName":{"type":"string","description":"The sender's bank or financial institution."},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code for the sender."}}},"PoolAccountPaymentProofRequest":{"type":"object","required":["amount","customerId","countryCode","reference","fileKey","timestamp"],"properties":{"amount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"The deposit amount in the major currency unit."},"customerId":{"type":"string","description":"The Afriex customer ID the deposit should be credited to. Applies when `reference` is a customer reference, in which case it must match that customer. When `reference` is the business's own pool-account reference the deposit is credited to the business and this field is not used for routing."},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the pool account."},"reference":{"type":"string","description":"The pool-account reference returned by `GET /api/v1/payment-method/pool-account`. Used to reconcile the deposit."},"fileKey":{"type":"string","description":"The S3 object key of the uploaded proof-of-payment file. Obtain this from `POST /api/v1/media/url` with `type: transaction` first; a URL requested without that type uploads to a different bucket and the key will be rejected as not found."},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when the payment was sent. Used for idempotency together with the other request fields."},"senderDetails":{"$ref":"#/components/schemas/PoolAccountPaymentProofSenderDetails"}}},"MediaURLRequest":{"type":"object","required":["fileName"],"properties":{"fileName":{"type":"string","description":"The name of the file to upload.","examples":["document.pdf"]},"type":{"type":"string","enum":["transaction","user"],"description":"The category of the file being uploaded. Use `transaction` for transaction-related files (e.g. a transactions CSV) and `user` for user identity documents. Defaults to `user` when omitted.\n"}}},"MediaURLResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","description":"The presigned URL for the requested upload operation.","examples":["https://s3.amazonaws.com/bucket/key?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."]},"key":{"type":"string","description":"A stable reference to the uploaded object. Attach this to a later request (e.g. a SWIFT payout invoice) rather than the presigned URL, which expires shortly after it is issued.\n","examples":["64f0c2a1e4b0a1b2c3d4e5f6/invoice.pdf"]},"expiresIn":{"type":"integer","description":"Number of seconds the presigned URL remains valid for the upload. Complete the PUT upload within this window; afterwards, request a fresh URL.\n","examples":[300]}}}}},"WebhookEventName":{"type":"string","description":"The webhook event identifier.","enum":["CUSTOMER.CREATED","CUSTOMER.UPDATED","CUSTOMER.DELETED","PAYMENT_METHOD.CREATED","PAYMENT_METHOD.UPDATED","PAYMENT_METHOD.DELETED","TRANSACTION.CREATED","TRANSACTION.UPDATED","CHECKOUT_SESSION.CREATED","POOL_DEPOSIT_REQUEST.REJECTED"]}}},"security":[{"ApiKey":[]}],"paths":{"/api/v1/customer":{"parameters":[{"$ref":"#/components/parameters/x-api-version"}],"post":{"operationId":"createCustomer","summary":"Create a new customer","description":"Creates a new customer for a business, with optional KYC information.","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fullName","email","phone","countryCode"],"properties":{"fullName":{"type":"string","description":"The full name of the customer.","examples":["John Doe"]},"email":{"type":"string","format":"email","description":"The email address of the customer.","examples":["john.doe@example.com"]},"phone":{"type":"string","description":"The phone number of the customer.","examples":["+2348192837465"]},"countryCode":{"type":"string","description":"The ISO 3166-1 alpha-2 country code of the customer (e.g., 'NG', 'US').","examples":["NG"]},"meta":{"type":"object","description":"Optional meta data you can attach to the customer."}}},"examples":{"basicCustomer":{"summary":"Minimal, name, email, phone, country","value":{"fullName":"Jane Smith","email":"jane.smith@example.com","phone":"+2348192837465","countryCode":"NG"}},"customerWithMeta":{"summary":"With custom meta data","value":{"fullName":"Jane Smith","email":"jane.smith@example.com","phone":"+2348192837465","countryCode":"NG","meta":{"externalId":"usr_abc123","tier":"premium"}}}}}}},"responses":{"201":{"description":"Customer created successfully. Returns the newly created customer object.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}},"examples":{"success":{"summary":"Customer created","value":{"data":{"name":"Jane Smith","email":"jane.smith@example.com","phone":"+2348192837465","customerId":"69d5ffe1ab82306f11b032f3","reference":"afx121011","countryCode":"NG","createdAt":"2026-04-08T07:12:33.519Z","updatedAt":"2026-04-08T07:12:33.519Z"}}}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingPhone":{"summary":"Missing required field (phone)","value":{"code":"INVALID_BUSINESS_CUSTOMER_REQUEST","error":"Invalid business customer request","details":{"errorMessage":"Invalid business customer request","friendlyMessage":"No customer phone provided"}}},"invalidEmail":{"summary":"Invalid email format","value":{"code":"INVALID_BUSINESS_CUSTOMER_REQUEST","error":"Invalid business customer request","details":{"errorMessage":"Invalid business customer request","friendlyMessage":"Invalid customer email provided: INVALID_EMAIL"}}}}}}},"409":{"description":"A customer with this email or phone already exists for the business. `details.data.customerId` carries the existing customer's id so you can adopt it without a follow-up lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"emailExists":{"summary":"Email already in use","value":{"code":"EMAIL_ALREADY_EXISTS","error":"Email already exists","details":{"errorMessage":"Email already exists","friendlyMessage":"","data":{"customerId":"69d5fff7ab82306f11b0330e"}}}},"phoneExists":{"summary":"Phone already in use","value":{"code":"PHONE_NUMBER_ALREADY_EXISTS","error":"Phone number already exists","details":{"errorMessage":"Phone number already exists","friendlyMessage":"","data":{"customerId":"69d5fff7ab82306f11b0330e"}}}}}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serverError":{"summary":"Unexpected server error","value":{"code":"INTERNAL_SERVER_ERROR","error":"It's not you, it's us, please reach out to support","details":{}}}}}}},"503":{"description":"Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serviceUnavailable":{"summary":"Upstream processor unavailable","value":{"code":"EXTERNAL_REQUEST_ERROR","error":"External request error","details":{}}}}}}}},"x-codeSamples":[{"lang":"TypeScript","label":"Afriex SDK","source":"const customer = await afriex.customers.create({\n fullName: \"John Doe\",\n email: \"john@example.com\",\n phone: \"+1234567890\",\n countryCode: \"US\",\n});\n"}]},"get":{"operationId":"listCustomers","summary":"Get customer list","description":"Retrieves a paginated list of customers.","tags":["Customers"],"parameters":[{"name":"page","in":"query","description":"Page number for pagination (starting from 0)","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"email","in":"query","description":"Filter by customer email address (exact match, case-insensitive).","required":false,"schema":{"type":"string","format":"email","examples":["john.doe@example.com"]}},{"name":"phone","in":"query","description":"Filter by customer phone number in E.164 format.","required":false,"schema":{"type":"string","examples":["+2348192837465"]}}],"responses":{"200":{"description":"List of customers retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"page":{"type":"integer","description":"Current page number"},"total":{"type":"integer","description":"Total number of customers matching the query"}}},"examples":{"success":{"summary":"Customer list retrieved","value":{"data":[{"name":"Addams Oshay","email":"addams@example.com","phone":"+15086340138","customerId":"6929843e2c4653277440acc0","reference":"afx121011","countryCode":"US","createdAt":"2025-11-28T11:15:10.812Z","updatedAt":"2025-11-28T11:15:10.812Z"},{"name":"Daniel Obirije","email":"daniel@example.com","phone":"+2347049861191","customerId":"6930610b0d8aab4a00b3f918","reference":"afx121011","countryCode":"NG","createdAt":"2025-12-03T16:10:51.291Z","updatedAt":"2025-12-03T16:10:51.291Z"}],"total":1448,"page":0}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingApiKey":{"summary":"Missing API key","value":{"code":"AUTHENTICATION_ERROR","error":"Authorization header is missing","details":{}}},"invalidApiKey":{"summary":"Invalid API key","value":{"code":"AUTHENTICATION_ERROR","error":"Invalid authorization header","details":{}}}}}}},"422":{"description":"Request failed schema validation. `details.friendlyMessage` carries the specific field error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validationError":{"summary":"Validation error","value":{"code":"VALIDATION_ERROR","error":"Validation error","details":{"errorMessage":"Validation error","friendlyMessage":"'page' must be a number"}}}}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serverError":{"summary":"Unexpected server error","value":{"code":"INTERNAL_SERVER_ERROR","error":"It's not you, it's us, please reach out to support","details":{}}}}}}},"503":{"description":"Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serviceUnavailable":{"summary":"Upstream processor unavailable","value":{"code":"EXTERNAL_REQUEST_ERROR","error":"External request error","details":{}}}}}}}},"x-codeSamples":[{"lang":"TypeScript","label":"Afriex SDK","source":"const response = await afriex.customers.list({\n page: 0,\n limit: 20,\n email: \"john@example.com\",\n});\n\nconsole.log(response.data); // Customer[]\nconsole.log(response.total); // Total count\n"}]}},"/api/v1/customer/{customerId}":{"parameters":[{"$ref":"#/components/parameters/x-api-signature"},{"$ref":"#/components/parameters/x-api-version"}],"get":{"operationId":"getCustomer","summary":"Get customer by ID","description":"Retrieves a specific customer by their unique identifier. The response includes the customer's `reference`, which is the value to supply as the pool-account `reference` when submitting a payment proof.","tags":["Customers"],"parameters":[{"name":"customerId","in":"path","description":"The unique identifier of the customer","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Customer retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}},"examples":{"success":{"summary":"Customer retrieved","value":{"data":{"name":"Jane Smith","email":"jane.smith@example.com","phone":"+2348192837465","customerId":"69d5ffe1ab82306f11b032f3","reference":"afx121011","countryCode":"NG","createdAt":"2026-04-08T07:12:33.519Z","updatedAt":"2026-04-08T07:12:33.519Z"}}}}}}},"400":{"description":"Invalid customer ID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validationError":{"summary":"Validation error","value":{"code":"VALIDATION_ERROR","error":"Failed to parse request. Issues: 'customerId' must be a string","details":{}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingApiKey":{"summary":"Missing API key","value":{"code":"AUTHENTICATION_ERROR","error":"Authorization header is missing","details":{}}},"invalidApiKey":{"summary":"Invalid API key","value":{"code":"AUTHENTICATION_ERROR","error":"Invalid authorization header","details":{}}}}}}},"404":{"description":"Customer not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"summary":"Customer not found","value":{"code":"BUSINESS_CUSTOMER_NOT_FOUND","error":"Business customer not found","details":{"errorMessage":"Business customer not found","friendlyMessage":""}}}}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serverError":{"summary":"Unexpected server error","value":{"code":"INTERNAL_SERVER_ERROR","error":"It's not you, it's us, please reach out to support","details":{}}}}}}},"503":{"description":"Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"serviceUnavailable":{"summary":"Upstream processor unavailable","value":{"code":"EXTERNAL_REQUEST_ERROR","error":"External request error","details":{}}}}}}}},"x-codeSamples":[{"lang":"TypeScript","label":"Afriex SDK","source":"const customer = await afriex.customers.get(\"customer-id\");\n"}]},"patch":{"operationId":"updateCustomer","summary":"Update customer profile","description":"Part
# --- truncated at 32 KB (179 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/afriex/refs/heads/main/openapi/afriex-business-openapi-original.json