Payment Methods API

Manage bank accounts, mobile money, crypto wallets, and virtual accounts.

Create Payment Method

const paymentMethod = await afriex.paymentMethods.create({
  channel: "BANK_ACCOUNT",
  customerId: "customer-id",
  accountName: "John Doe",
  accountNumber: "1234567890",
  countryCode: "NG",
  institution: {
    institutionCode: "044",
    institutionName: "Access Bank",
  },
});

Creatable Channels:

Channel	Description
`BANK_ACCOUNT`	Bank transfer
`MOBILE_MONEY`	Mobile money (M-Pesa, MTN, etc.)
`VIRTUAL_BANK_ACCOUNT`	Virtual bank account
`ACH_BANK_ACCOUNT`	US ACH bank account
`INTERAC`	Interac (Canada)
`UPI`	Unified Payments Interface (India)
`SWIFT`	International SWIFT transfer
`WE_CHAT`	WeChat Pay (China)
`ALIPAY`	Alipay (China)
`PAYBILL_TILL`	M-Pesa Paybill/Till (Kenya)

CARD, CRYPTO, POOL_ACCOUNT, RFP, and VIRTUAL_CARD are response-only channels — they're returned by get()/list() but can't be passed to create().

Get Payment Method

const paymentMethod = await afriex.paymentMethods.get("payment-method-id");

List Payment Methods

const response = await afriex.paymentMethods.list({
  page: 1,
  limit: 20,
  channel: ["BANK_ACCOUNT", "MOBILE_MONEY"],
  currencies: ["USD", "NGN"],
  status: ["active", "pending"],
});

Parameters:

Field	Type	Description
`page`	`number`	Page number, starting from 0
`limit`	`number`	Items per page (max 100)
`channel`	`string \| string[]`	Filter by one or more payment channels
`currencies`	`string \| string[]`	Filter by one or more 3-letter currency codes
`capabilities`	`string \| string[]`	Filter by capability. Only `WITHDRAW` is currently supported; defaults to `WITHDRAW`
`status`	`string \| string[]`	Filter by status. Defaults to `active,pending`

Delete Payment Method

await afriex.paymentMethods.delete("payment-method-id");

Get Institutions

List supported banks or mobile money providers:

const institutions = await afriex.paymentMethods.getInstitutions({
  channel: "BANK_ACCOUNT",
  countryCode: "NG",
});

// Returns: Institution[]
// { institutionId, institutionName, institutionCode }

Resolve Institution Code

Resolve a bank code (SWIFT code or US routing number) to the corresponding institution name:

const result = await afriex.paymentMethods.resolveInstitutionCode({
  searchTerm: "021000021",
  country: "US",
  codeType: "routing_number",
});

// Returns: { bankName: 'JPMORGAN CHASE BANK' } or null if not found

country defaults to US and accepts any ISO country code for swift_code lookups; routing_number is only supported when country is US.

Resolve Account

Verify account details before creating a payment method:

const accountInfo = await afriex.paymentMethods.resolveAccount({
  channel: "BANK_ACCOUNT",
  accountNumber: "1234567890",
  institutionCode: "044",
  countryCode: "NG",
});

// Returns: { recipientName, recipientEmail, recipientPhone }

Get Crypto Wallet

Get or create a crypto wallet address:

const response = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT", // or 'USDC'
  customerId: "optional-customer-id",
});

// Returns: { data: [{ address, network }], total, page }

Crypto wallets are production-only.

List Virtual Accounts

Get existing virtual accounts for a customer:

const response = await afriex.paymentMethods.listVirtualAccounts({
  customerId: "customer-id",
  currency: "USD",
});

// Returns: { data: VirtualAccount[], total, page }

Create Virtual Account

Generate a new virtual account:

// With fixed amount label
const account = await afriex.paymentMethods.createVirtualAccount({
  currency: "USD",
  label: "SALES",
  customerId: "optional-customer-id",
});

// OR with specific amount
const account = await afriex.paymentMethods.createVirtualAccount({
  currency: "NGN",
  amount: 50000,
  customerId: "customer-id",
});

// Returns single VirtualAccount object

Parameters:

Field	Type	Required	Description
`currency`	`string`	Yes	`USD`, `NGN`, `GBP`, or `EUR`
`label`	`string`	No*	Descriptive label for the account
`amount`	`number`	No*	Specific transaction amount
`customerId`	`string`	-	Optional customer ID to associate

*Mutually exclusive: provide label OR amount, not both.

List Pool Accounts

Get the pool account for a supported country:

const poolAccount = await afriex.paymentMethods.listPoolAccounts({
  customerId: "customer-id",
  country: "NG",
});

// Returns: PaymentMethod

Pool accounts are shared across multiple customers in a country. Use the reference on the returned payment method to reconcile incoming deposits.

Virtual accounts and pool accounts are production-only.

On this page