---
title: "Create a payment method"
method: POST
path: "/api/v1/payment-method"
tags: ["Payment Methods"]
---

# Create a payment method

`POST /api/v1/payment-method`

## Request

- Base URL: `https://sandbox.api.afriex.com`
- URL: `https://sandbox.api.afriex.com/api/v1/payment-method`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/afriex/apis/afriex-business-api/docs/api/v1/payment-method/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

Account numbers are normalised before they are stored and returned: a mobile money number is rewritten to E.164 with a leading `+`, and an IBAN is returned in its normalised form.

## Request body

- object
  - `channel` 'BANK_ACCOUNT' | 'MOBILE_MONEY' | 'VIRTUAL_BANK_ACCOUNT' | 'ACH_BANK_ACCOUNT' | 'INTERAC' | 'UPI' | 'SWIFT' | 'WE_CHAT' | 'ALIPAY', required: The payment method channel
  - `customerId` string: The unique identifier of the customer.
  - `type` 'DEPOSIT' | 'WITHDRAW': The capability of this payment method. DEPOSIT means funds can be pulled from this method (e.g. charge/collect from the customer). WITHDRAW means funds can be sent to this method (e.g. pay out to the customer). If omitted, defaults to WITHDRAW.
  - `accountName` string: The name of the account holder. Must use Latin-script letters (A-Z / a-z, including accented forms such as é, ñ, ü, ç) or Chinese (Han) characters, digits (0-9), spaces and the characters & ( ) + , - . / : ? and apostrophe; it must contain at least one letter. Names in other scripts (e.g. Arabic, Cyrillic) or containing other symbols are rejected. Exception: China-facing payouts on the `WE_CHAT` and `ALIPAY` channels accept the beneficiary's local-script (e.g. Chinese) name. On `ALIPAY`, and on `WE_CHAT` with `currency` CNY, the name must be split into first and last name with a space (e.g. "张 伟" or "Wei Zhang").
  - `accountNumber` string: The account number. For a BANK_ACCOUNT in NG it must be exactly 10 digits. For a BANK_ACCOUNT in a country that uses IBANs (e.g. EUR) it must be a valid IBAN. For MOBILE_MONEY send digits only, with no leading `+` (country code plus national number); the length is checked for some countries and the number must be a valid phone number for `countryCode`.
  - `countryCode` string, required: The ISO 3166-1 alpha-2 country code. This has to be one of the countries we support
  - `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.
  - `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.
  - `sender` 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.
  - `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.
  - `meta` object: Optional meta data to attach to the payment method. It is stored as sent and returned as `meta` on the payment method.
  - `walletTag` string: Optional. Tags the payment method to one of your wallets (`DEPOSIT`, `WITHDRAW` or `FEE`). Stored as sent and not returned on the payment method.
  - `amount` union: A monetary amount. Accepts a number or a numeric string; responses return amounts as strings. Must be greater than zero.
    - number
    - string
  - `wechatId` string: Optional WeChat ID, sent alongside the phone number in `accountNumber`. Only used on the `WE_CHAT` channel; ignored on every other channel.
  - `district` string: The receiver's district as an ISO 3166-2 code (e.g. `BD-13`). Only accepted on a `MOBILE_MONEY` payment method in Bangladesh (`countryCode` `BD`), and needed there: a payout to a Bangladesh wallet saved without it is refused. Rejected on every other channel and country.

## Response `201`

Payment method created 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.
- `401`: Unauthorized - Invalid business API key.
- `404`: The customer could not be resolved.
- `422`: This payment method cannot be used: it is not available for the country, currency or channel you sent.
- `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)