Skip to main content
GET
Afriex SDK
A pool account is a shared, Afriex-managed account that customers pay into. Afriex uses the reference to attribute incoming funds to your business. Important: Pool accounts are only active in production and do not work in sandbox.

How the call works

  1. Call this endpoint with country (required). Optionally pass customerId to scope the response to a specific end-user.
  2. Afriex returns the pool account (account name, account number, institution) as a PaymentMethod, along with a reference.
  3. Share the account details with your customer so they can pay in. When Afriex receives the inbound funds, it uses the reference to attribute the deposit on your account.

The reference field

Every response includes a reference string. Persist it alongside the deposit you expect and use it to reconcile incoming pool deposits. When you pass a customerId, the response reference matches it, so the deposit can be attributed back to that customer on your side.

Currency is derived from country

Unlike dedicated virtual accounts, this endpoint does not take a currency parameter. The currency is determined by the country code (for example, NG resolves to NGN). Pool accounts are only available in countries where Afriex operates a pool; an unsupported country code returns a 400.

When you have no pool account

If your business has no pool account in the country you ask for, the call returns 404 with BUSINESS_PAYMENT_METHOD_NOT_FOUND. Retrying returns the same answer until one is set up for your business, so don’t retry it. Contact support@afriex.com if you expect to have one.

Authorizations

x-api-key
string
header
required

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. Manage your keys and their permissions under Developer → API keys in the dashboard.

A request whose key does not carry the permission the target endpoint requires is rejected with 401 Unauthorized, the same response an unrecognised, malformed, revoked or disabled key returns. The API does not distinguish the two cases on the wire.

See the Permissions reference for the permission each endpoint requires.

Headers

x-api-version
string

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.

x-api-signature
string

Signature of the request payload, used for request authentication where payload signing is enabled for your business.

Query Parameters

country
string
required

ISO 3166-1 alpha-2 country code.

Example:

"NG"

customerId
string

Optional customer ID to associate with this account.

amount
number

Optional positive amount. Accepted but ignored.

reference
string

Optional merchant-supplied reference. Accepted but ignored.

Response

Pool account returned successfully.

data
object

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.