# Afriex Business API

- [Afriex Business API](https://docs.afriex.com/index.md): Build seamless payment experiences with the Afriex Business API
- [Quickstart](https://docs.afriex.com/quickstart.md): Send your first sandbox payout, from API key to settled transaction
- [Integration Guide](https://docs.afriex.com/development.md): Best practices for integrating the Afriex Business API
- [Changelog](https://docs.afriex.com/changelog.md): Changes to how the Afriex Business API behaves, newest first.
- [Supported Currencies & Payment Rails](https://docs.afriex.com/guides/supported-currencies.md): Complete list of countries, currencies, and payment channels available through the Afriex Business API
- [Connecting the Pieces](https://docs.afriex.com/guides/connecting-the-pieces.md): How Customers, Payment Methods, and Transactions link together
- [Testing in Sandbox](https://docs.afriex.com/guides/testing-in-sandbox.md): The complete reference for building and testing your integration against the Afriex sandbox: test values, deterministic outcomes, virtual account transfers, OTP flow, balance topups, and webhook drills.
- [Afriex SDK](https://docs.afriex.com/sdk/introduction.md): TypeScript SDK for the Afriex Business API: type-safe, modular, and production-ready
- [Webhooks](https://docs.afriex.com/sdk/webhooks.md): Verify webhook signatures and handle event notifications with the SDK
- [MCP Server](https://docs.afriex.com/mcp/introduction.md): Use the Afriex Business API with AI assistants via the Model Context Protocol
- [Connecting MCP Clients](https://docs.afriex.com/mcp/connecting.md): Connect Claude Desktop, Claude Code, and Cursor to the Afriex MCP server
- [Introduction](https://docs.afriex.com/api-reference/introduction.md): Welcome to the Afriex Business API
- [Authentication](https://docs.afriex.com/api-reference/authentication.md): Get an API key, send it with every request, and keep it safe.
- [Permissions](https://docs.afriex.com/api-reference/permissions.md): The permission each Afriex Business API endpoint requires, plus how keys and permissions relate.
- [IP allowlisting](https://docs.afriex.com/api-reference/ip-allowlisting.md): Restrict API access to your servers. One list covers every API key in your business.
- [Idempotency](https://docs.afriex.com/api-reference/idempotency.md): Retry a transaction create without creating a second transaction: what the idempotency key and reference do, what a duplicate returns, and how to recover after a timeout.
- [Errors](https://docs.afriex.com/api-reference/errors.md): The error format, what each HTTP status means, and which errors to retry.
- [Pagination](https://docs.afriex.com/api-reference/pagination.md): Page through list endpoints with page and limit: the response shape, the sort order of each list, and how to read a list that changes while you page.
- [Rate limits](https://docs.afriex.com/api-reference/rate-limits.md): How many requests your business can send, the headers that tell you where you stand, and what to do with a 429.
- [Models](https://docs.afriex.com/api-reference/models.md): Data models, enumerations, and field references for the Afriex Business API
- [Get Balance](https://docs.afriex.com/api-reference/endpoint/balance/get.md): Returns one wallet's balances in the provided currencies, as a flat currency-to-amount map: the **Payout (Withdraw) wallet** by default, the **Fee wallet** with `walletType=FEE`, or the **Collection (Deposit) wallet** with `walletType=DEPOSIT`. The Collection wallet is the one that `settlement: "req…
- [Checkout Flow Guide](https://docs.afriex.com/api-reference/endpoint/checkout-sessions/user-flow-guide.md): Step-by-step guide for the hosted Afriex Checkout payment experience
- [Create Checkout Session](https://docs.afriex.com/api-reference/endpoint/checkout-sessions/create.md): Creates a hosted checkout session for a customer and returns a `checkoutUrl` that the customer should be redirected to in order to complete payment. The session captures the merchant intent (amount, currency, merchant reference, customer details, and allowed payment channels) and is identified end-t…
- [Get Exchange Rates](https://docs.afriex.com/api-reference/endpoint/rates/get.md): Retrieves real-time exchange rates.
- [Create Customer](https://docs.afriex.com/api-reference/endpoint/customers/create.md): Creates a new customer for a business. `phone` is validated against `countryCode` and stored in E.164 format. If you post the email of a customer that was previously deleted, that customer is reactivated (its stored `countryCode` is kept) and the call still returns `201`.
- [List Customers](https://docs.afriex.com/api-reference/endpoint/customers/list.md): Retrieves a paginated list of customers.
- [Get Customer](https://docs.afriex.com/api-reference/endpoint/customers/get.md): 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.
- [Update Customer](https://docs.afriex.com/api-reference/endpoint/customers/update.md): Partially updates a customer's profile. Send at least one of `fullName`, `email`, or `phone`; omitted fields are left unchanged. Unrecognised keys are ignored, and a body with none of the three recognised keys fails with `422`. `phone` is validated against the customer's stored `countryCode` (it can…
- [Delete Customer](https://docs.afriex.com/api-reference/endpoint/customers/delete.md): Deletes a specific customer by their unique identifier.
- [Update Customer KYC](https://docs.afriex.com/api-reference/endpoint/customers/update-kyc.md): Partially updates a customer's KYC information.
- [Verify Customer](https://docs.afriex.com/api-reference/endpoint/customers/verify.md): Runs an identity verification against a customer document. Today the only supported `docType` is `BVN` (Nigeria); `docValue` is the document number. Verification is rate limited per business. The `200` response carries the customer's stored KYC documents in `meta.kyc.data`.
- [Create Payment Method](https://docs.afriex.com/api-reference/endpoint/payment-methods/create.md): Creates a new payment method. `accountName`, `accountNumber` and `institution` are required for every channel except UPI and INTERAC, which take no `institution`, and VIRTUAL_BANK_ACCOUNT, which takes none of the three.
- [List Payment Methods](https://docs.afriex.com/api-reference/endpoint/payment-methods/list.md): Retrieves a paginated list of payment methods.
- [Get Payment Method](https://docs.afriex.com/api-reference/endpoint/payment-methods/get.md): Retrieves a specific payment method by its unique identifier.
- [Delete Payment Method](https://docs.afriex.com/api-reference/endpoint/payment-methods/delete.md): Removes a payment method from the system.
- [List Institutions](https://docs.afriex.com/api-reference/endpoint/payment-methods/institution.md): Retrieves a list of banks or mobile money providers available for a specific country.
- [Institution Codes](https://docs.afriex.com/api-reference/endpoint/payment-methods/institution-codes.md): Resolves a bank code (SWIFT code or US routing number) to the corresponding bank or institution name.
- [Resolve Payment Method](https://docs.afriex.com/api-reference/endpoint/payment-methods/resolve.md): Resolves payment method user information for bank accounts or mobile money.
- [Get or Create Crypto Wallet](https://docs.afriex.com/api-reference/endpoint/payment-methods/crypto-wallet.md): Retrieves an existing crypto wallet or creates a new one for the specified crypto asset. **Important:** This endpoint is **only active in production** and does **not work in sandbox**. Supports idempotency to prevent duplicate wallet creation: a call made while another crypto-wallet call from your b…
- [List Virtual Accounts](https://docs.afriex.com/api-reference/endpoint/payment-methods/virtual-account.md): Returns every active virtual account for the resolved customer-or-owner and currency. Read-only: when no virtual account exists, the response is **200** with `data: []`.
- [Create Virtual Account](https://docs.afriex.com/api-reference/endpoint/payment-methods/virtual-account-create.md): Creates a new virtual account for the resolved customer-or-owner and currency. Pass `customerId` to mint the VA for a specific end-user; omit it to mint one for the business owner.
- [Get Pool Account](https://docs.afriex.com/api-reference/endpoint/payment-methods/pool-account.md): Returns the pool account for the supplied `country`. Use the `reference` on the response to reconcile incoming deposits; it is a shortened form such as `afx1234` (with a customer, `afx1234012`). Each call also sends a `PAYMENT_METHOD.UPDATED` webhook carrying the pool account.
- [Generate Upload URL](https://docs.afriex.com/api-reference/endpoint/media/generate-upload-url.md): Generates a presigned S3 URL that the caller can use to upload a file (e.g. a KYC document) directly to Afriex's secure storage. The returned URL is time-limited and scoped to the requested operation. The file name is sanitised before it is used: any directory part is dropped, characters outside `A-…
- [Create Transaction](https://docs.afriex.com/api-reference/endpoint/transactions/create.md): Create a new transaction to process a payment for a customer. Use `type: WITHDRAW` to send funds to a destination payment method (requires `destinationId`), `type: DEPOSIT` to pull funds from a source payment method (requires `sourceId`), or `type: SWAP` to convert funds between currencies within th…
- [List Transactions](https://docs.afriex.com/api-reference/endpoint/transactions/list.md): Retrieves a paginated list of transactions.
- [Quote a Withdrawal](https://docs.afriex.com/api-reference/endpoint/transactions/quote.md): Returns what a withdrawal would cost, priced by the same code that charges it, without creating anything. Type exactly one of `sourceAmount` (what you send) or `destinationAmount` (what the recipient receives); the other is derived from it. The side you type is returned as `anchor`.
- [Get Transaction](https://docs.afriex.com/api-reference/endpoint/transactions/get.md): Retrieves a specific transaction by its unique identifier.
- [Authorize Transaction](https://docs.afriex.com/api-reference/endpoint/transactions/authorize.md): Completes a transaction that was created in a `CUSTOMER_ACTION_REQUIRED` state and needs an extra authorization step (for example, a one-time password on a mobile-money deposit). The body is discriminated by `type`; today the only supported variant is `OTP`. Your business must have a webhook URL set…
- [Get Settlement Advice](https://docs.afriex.com/api-reference/endpoint/transactions/advice.md): Returns a short-lived presigned download URL for the settlement & remittance advice PDF auto-generated for a USD withdrawal from your collection wallet (a withdrawal created with `settlement: "request"`). The advice is issued with status `PENDING` when the withdrawal is created and regenerated with…
- [Submit Pool-Account Payment Proof](https://docs.afriex.com/api-reference/endpoint/transactions/pool-account-proof.md): Submits proof of a deposit made to the business pool account. The request creates a business deposit transaction in `IN_REVIEW` status; an operator confirms the bank inflow before the funds are credited. The response returns that transaction. Duplicate submissions of the same business, customer, amo…
- [List Payment Batches](https://docs.afriex.com/api-reference/endpoint/payment-batches/list.md): Returns the batches belonging to the calling business. Requires the `PAYMENT_BATCH.READ` key permission.
- [Create Payment Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/create.md): Creates an empty batch. Add recipients with the recipient endpoints, then start the payouts with POST /api/v1/payment-batch/{batchId}/withdraw. Requires the `PAYMENT_BATCH.CREATE` key permission.
- [Get Payment Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/get.md): Requires the `PAYMENT_BATCH.READ` key permission.
- [Update Payment Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/update.md): Replaces the batch's name and funding method. Send both: the batch is updated whole. Requires the `PAYMENT_BATCH.UPDATE` key permission.
- [Delete Payment Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/delete.md): Requires the `PAYMENT_BATCH.DELETE` key permission.
- [List Batch Recipients](https://docs.afriex.com/api-reference/endpoint/payment-batches/list-recipients.md): Requires the `PAYMENT_BATCH.READ` key permission.
- [Add Recipient to Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/add-recipient.md): Pass `paymentMethodId` to update that saved account of the business and add it to the batch, instead of creating a new one. Requires the `PAYMENT_BATCH.UPDATE` key permission.
- [Bulk Add Recipients to Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/add-recipients-bulk.md): Adds each recipient independently and reports which were added. The results are keyed by account number. Requires the `PAYMENT_BATCH.UPDATE` key permission.
- [Update Recipient in Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/update-recipient.md): Replaces the recipient's account details and amount. Pass `paymentMethodId` to update that saved account in place. A `recipientId` that is not in this batch is refused with `400`, not `404`. Requires the `PAYMENT_BATCH.UPDATE` key permission.
- [Remove Recipient from Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/remove-recipient.md): Removes the recipient from this batch only; the saved account is kept. A `recipientId` that is not in this batch is refused with `400`, not `404`. Requires the `PAYMENT_BATCH.UPDATE` key permission.
- [Withdraw Batch](https://docs.afriex.com/api-reference/endpoint/payment-batches/withdraw.md): Creates a payout for every recipient in the batch in one call and records the run as a session. The payouts settle asynchronously, so a webhook callback URL must be configured. Requires the `TRANSACTION.WITHDRAW.CREATE` key permission.
- [List Batch Sessions](https://docs.afriex.com/api-reference/endpoint/payment-batches/list-sessions.md): Requires the `TRANSACTION.HISTORY.READ` key permission.
- [Register SME](https://docs.afriex.com/api-reference/endpoint/sme-registration/register.md): Registers a business as its own SME so that dedicated virtual accounts are issued under the business's own legal entity rather than the shared default. The flow is stateful and driven by this single endpoint: the `step` field selects the payload carried in `data`. Call the steps in order: `INITIATE`…
- [Get SME Registration Status](https://docs.afriex.com/api-reference/endpoint/sme-registration/status.md): Returns the most recent SME registration status for the authenticated business. Once the registration has been submitted, the response also includes the latest review outcome. Requires the `COMPLIANCE.KYB.READ` key permission.
- [Simulate Transaction Outcome](https://docs.afriex.com/api-reference/endpoint/transactions/simulate.md): Sandbox only; returns 403 in production. Completes a pending sandbox deposit or payout with the outcome you choose, and your balance and transaction webhook behave as they would in production. The transaction must still be `PENDING`, `PROCESSING` or `UNKNOWN`: a deposit waiting for an OTP must be au…
- [Top Up Sandbox Balance](https://docs.afriex.com/api-reference/endpoint/balance/topup.md): Credits the business's Payout wallet, or its Fee or Collection wallet with `walletType: FEE` or `DEPOSIT`, with the specified amount and currency. **This endpoint is only available in the sandbox environment and will return a `403 Forbidden` response in production.** Use it during integration develo…
- [Simulate Virtual Account Transfer](https://docs.afriex.com/api-reference/endpoint/payment-methods/virtual-account-simulate-transfer.md): Sandbox only; returns 403 in production. Credits a bank transfer into one of your sandbox virtual accounts, the way the account provider's deposit notification would, so balances and your transaction webhook behave as in production. Pass the account number; for an account created with an `amount` (a…
- [Trigger Test Webhook](https://docs.afriex.com/api-reference/endpoint/webhooks/trigger.md): Fires a real signed webhook to the business's configured callback URL using a real entity (customer, payment method, transaction, or checkout session) as the payload. Useful for testing webhook handlers in sandbox without manufacturing the underlying activity. **This endpoint is only available in th…
- [Introduction](https://docs.afriex.com/api-reference/endpoint/webhooks/introduction.md): Webhook overview, security, and verification
- [Customer Events](https://docs.afriex.com/api-reference/endpoint/webhooks/customer-events.md): Afriex delivers real-time notifications to your configured webhook URL whenever a customer is **created**, **updated**, or **deleted**.
- [Payment Method Events](https://docs.afriex.com/api-reference/endpoint/webhooks/payment-method-events.md): Afriex delivers real-time notifications to your configured webhook URL whenever a payment method is **created**, **updated**, or **deleted** for a customer.
- [Transaction Events](https://docs.afriex.com/api-reference/endpoint/webhooks/transaction-events.md): Afriex sends real-time webhook notifications to your configured URL whenever a transaction is **created** or **updated**.
- [Checkout Session Events](https://docs.afriex.com/api-reference/endpoint/webhooks/checkout-session-events.md): Afriex delivers a webhook to your configured URL when a hosted checkout session is created. It is the only checkout session event: it is sent once, when you create the session, and says nothing about payment. Track the payment with transaction events, and find the session's deposit with `GET /api/v1…
- [Pool Deposit Events](https://docs.afriex.com/api-reference/endpoint/webhooks/pool-deposit-events.md): Afriex delivers a webhook to your configured URL when a pool account deposit you submitted is rejected during review.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)

## Optional

- [Status](https://afriex.statuspage.io)
- [Support](mailto:support@afriex.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.