Connecting the Pieces: How Customers, Payment Methods, and Transactions link together
Get Balance: Returns the balances of the business in the provided currencies.
Top Up Sandbox Balance: Credits the business wallet with the specified amount and currency. This endpoint is only available in the sandbox/staging environment and will return a 403 Forbidden response in production. Use it during integration development to top up your test balance without making real transfers.
Create Checkout Session: 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-to-end.
Checkout Flow Guide: Step-by-step guide for the hosted Afriex Checkout payment experience
Create Customer: Creates a new customer for a business, with optional KYC information.
Delete Customer: Deletes a specific customer by their unique identifier.
Get Customer: Retrieves a specific customer by their unique identifier.
List Customers: Retrieves a paginated list of customers.
Update Customer: Partially updates a customer's profile. Send at least one of fullName, email, or phone; omitted fields are left unchanged.
Verify Customer: 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.
Generate Upload URL: 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.
Get or Create Crypto Wallet: 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 on staging/dev. Supports idempotency to prevent duplicate wallet creation. Currently supports USDT and USDC assets. Send a GET request.
Get Pool Account: Returns the pool account for the supplied country. Use the reference on the response to reconcile incoming deposits.
Resolve Payment Method: Resolves payment method user information for bank accounts or mobile money.
List Virtual Accounts: 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: 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.
Register SME: 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: 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 an API key with admin permission.
Authorize Transaction: 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.
Create Transaction: 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 the same account.
Get Transaction: Retrieves a specific transaction by its unique identifier.
Trigger Test Webhook: 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 the production environment.