--- title: "Get the business pool account" method: GET path: "/api/v1/payment-method/pool-account" tags: ["Payment Methods"] --- # Get the business pool account `GET /api/v1/payment-method/pool-account` ## Request - Base URL: `https://sandbox.api.afriex.com` - URL: `https://sandbox.api.afriex.com/api/v1/payment-method/pool-account` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `country` string, required - `customerId` string - `amount` number - `reference` string ## Response `200` Pool account returned successfully. - object - `data` PaymentMethod: 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. - `paymentMethodId` string: The unique identifier for the payment method. - `customerId` string: The unique identifier of the customer. - `reference` string: Identifier to reconcile incoming deposits against. - `institution` PaymentMethodInstitution: On a payment method, only `institutionId`, `institutionName`, `institutionCode`, `institutionAddress` and the correspondent bank fields are returned. The address components and `institutionBranch` are accepted when you create one but are not returned on it; `institutionBranch` is returned by the institution list. - `institutionId` string: The unique identifier of the bank or mobile money provider if required. - `institutionName` string: The name of the bank or mobile money provider if required. - `institutionCode` string: The code of the bank or mobile money provider. - `institutionAddress` string: The address of the bank or mobile money provider if required. - `institutionAddressLine1` string: Optional. First line of `institutionAddress`, for SWIFT payment methods. Used ahead of `recipientAddressLine1`. - `institutionAddressCity` string: Optional. City of `institutionAddress`, for SWIFT payment methods. - `institutionAddressState` string: Optional. State of `institutionAddress`, for SWIFT payment methods. - `institutionAddressZip` string: Optional. Postal or ZIP code of `institutionAddress`, for SWIFT payment methods. - `institutionAddressCountry` string: Optional. Country of `institutionAddress`, for SWIFT payment methods. - `institutionBranch` string: The branch of the bank. Required when creating a BANK_ACCOUNT payment method in CNY. Bank lists return it too, often as an empty string. - `correspondentBankName` string: The correspondent (intermediary) bank name. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices. - `correspondentBankAccountNumber` string: The correspondent (intermediary) bank account number. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices. - `transaction` PaymentMethodTransaction - `transactionInvoice` string: The invoice filename (S3 object key) for the transaction, as returned by the media upload endpoint. - `transactionNarration` string: The optional reason for the transaction. - `recipient` PaymentMethodRecipient: On a payment method, only `recipientEmail`, `recipientPhone`, `recipientAddress` and `recipientName` are returned. The other fields are accepted when you create one but are not returned on it. - `recipientEmail` string, email: The email address of the recipient if needed. - `recipientPhone` string: The phone number of the recipient in E.164 format. - `recipientAddress` string: The address of the recipient if needed. - `recipientAddressLine1` string: Optional. First line of `recipientAddress`. Used on SWIFT payment methods when `institutionAddressLine1` is not sent. - `recipientAddressCity` string: Optional. City of `recipientAddress`. - `recipientAddressState` string: Optional. State of `recipientAddress`. - `recipientAddressZip` string: Optional. Postal or ZIP code of `recipientAddress`. - `recipientAddressCountry` string: Optional. Country of `recipientAddress`. - `recipientIdType` 'national_id' | 'passport' | 'drivers_license' | 'voters_card' | 'residence_permit' | 'bvn' | 'tax_id': The type of the recipient's ID. Needed, with `recipientIdNumber`, for BANK_ACCOUNT payment methods in CNY, where it is recorded as the recipient's KYC. - `recipientIdNumber` string: The number of the ID named by `recipientIdType`. Needed for BANK_ACCOUNT payment methods in CNY. - `recipientUpiId` string: The recipient's UPI ID. Used on UPI payment methods; when omitted, `accountNumber` is used. - `recipientName` string: The name of the recipient if needed. - `channel` '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': The payment method channel. - `countryCode` string: The ISO 3166-1 alpha-2 country code. - `currency` string: 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` string[]: 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` string: Name of the account holder. Present for account-shaped channels. - `accountNumber` string: Account number. Present for account-shaped channels, except INTERAC, which returns none. For UPI it carries the recipient phone number, not the UPI ID. - `routingNumber` string: Bank routing number. Present for account-shaped channels that carry one (e.g. ACH bank accounts). - `bankAddress` PaymentMethodBankAddress: 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. - `line1` string: First line of the bank's street address. - `line2` string: Second line of the bank's street address, when present. - `city` string: City. - `state` string: State or region, when present. - `zip` string: Postal or ZIP code. - `country` string: Country, as supplied by the provider. - `status` 'active' | 'pending' | 'deleted' | 'expired' | 'blocked': Lifecycle status of the payment method. - `last4` string: Last 4 digits of the card. CARD channel only. - `brand` 'Visa' | 'MasterCard' | 'Discover' | 'American Express' | 'JCB' | 'Diners Club' | 'Eftpos Australia' | 'UnionPay' | 'Unknown': Card brand. CARD channel only. - `expiration` object: Card expiration. CARD channel only. - `month` integer - `year` integer - `cardName` string: Name on the card. CARD channel only. - `expiresInMinutes` integer: Minutes until a dynamic virtual account expires, when applicable. - `amount` union: The amount stored with the payment method, as you sent it (a number or a numeric string), or the requested amount for a dynamic virtual account, when applicable. - number - string - `extra` object: Additional channel-specific properties. - `meta` object: The meta data you attached to the payment method when you created it. ## Other responses - `400`: Invalid request, for example a missing or unsupported country code. - `401`: Unauthorized - Invalid business API key. - `404`: No pool account is configured for the business in this country. Retrying returns the same answer until one is set up. - `500`: Server error. - `503`: Temporarily unavailable: an upstream service failed or timed out, or the API is momentarily offline. Retry with backoff and honour the Retry-After header when present. --- [API](https://skmtc.dev/afriex/apis/afriex-business-api.md) - [All operations](https://skmtc.dev/afriex/apis/afriex-business-api/llms.txt) - [OpenAPI document](https://skmtc.dev/afriex/apis/afriex-business-api/revisions/d94198b6c256?raw)