> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payment Method

> Creates a new payment method.

Create a new payment method for a customer. Supported channels include bank accounts, mobile money, SWIFT, UPI, Interac, and WeChat.

> Please note that fields without values are not included in the response. This includes fields with empty strings, null values, and undefined values.

<Note>
  **`accountName` character rules.** For every channel except `WE_CHAT` and `ALIPAY`, the account holder's name must use only Latin-script letters (A-Z / a-z, including accented forms such as `é`, `ñ`, `ü`, `ç`), digits (0-9), spaces, and the characters `&`, `(`, `)`, `+`, `,`, `-`, `.`, `/`, `:`, `?`, and apostrophe (`'`). At least one letter is required. Names in non-Latin scripts (e.g. Arabic, Chinese, Cyrillic) or containing other symbols are rejected. For `WE_CHAT` and `ALIPAY` payouts, submit the beneficiary's local-script name (e.g. Chinese characters) as it appears on their wallet.
</Note>


## OpenAPI

````yaml POST /api/v1/payment-method
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.8
  description: >-
    Welcome to the Afriex Business API. This API allows you to manage customers,
    process payments, handle payouts, and receive real-time notifications via
    webhooks.


    For detailed guidance on authentication, pagination, error handling, and
    webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
    the top bar. The guide provides a step-by-step instructions to help you
    integrate seamlessly.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: eng@afriex.co
    url: https://docs.afriex.com
  license:
    name: Proprietary
    url: https://www.afriex.com/terms-and-condition
servers:
  - url: https://sandbox.api.afriex.com
    description: Staging Base URL
  - url: https://api.afriex.com
    description: Production Base URL
security:
  - ApiKey: []
tags:
  - name: Customers
    description: Create and manage your customers.
  - name: Payment Methods
    description: Register and resolve customer payout and collection methods.
  - name: Transactions
    description: Create and track deposits, withdrawals, and swaps.
  - name: Balance
    description: View and top up your business wallet balances.
  - name: Rates
    description: Fetch real-time exchange rates.
  - name: Checkout Sessions
    description: Create hosted checkout sessions.
  - name: Webhooks
    description: Webhook event payloads and sandbox webhook testing.
  - name: Media
    description: Generate presigned URLs for secure file uploads.
paths:
  /api/v1/payment-method:
    parameters:
      - $ref: '#/components/parameters/x-api-signature'
      - $ref: '#/components/parameters/x-api-version'
    post:
      tags:
        - Payment Methods
      summary: Create a payment method
      description: Creates a new payment method.
      operationId: createPaymentMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - channel
                - accountName
                - accountNumber
                - countryCode
                - institution
              properties:
                channel:
                  type: string
                  description: The payment method channel
                  enum:
                    - BANK_ACCOUNT
                    - MOBILE_MONEY
                    - VIRTUAL_BANK_ACCOUNT
                    - ACH_BANK_ACCOUNT
                    - INTERAC
                    - UPI
                    - SWIFT
                    - WE_CHAT
                    - ALIPAY
                    - PAYBILL_TILL
                customerId:
                  $ref: '#/components/schemas/customerId'
                  description: >-
                    Optional. The customer to attach this payment method to.
                    When omitted, it is attached to the business owner.
                type:
                  type: string
                  description: >
                    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.
                  enum:
                    - DEPOSIT
                    - WITHDRAW
                accountName:
                  type: string
                  description: >-
                    The name of the account holder. Must use Latin-script
                    letters (A-Z / a-z, including accented forms such as é, ñ,
                    ü, ç), digits (0-9), spaces and the characters & ( ) + , - .
                    / : ? and apostrophe; it must contain at least one letter.
                    Names in non-Latin scripts (e.g. Arabic, Chinese, Cyrillic)
                    or containing other symbols are rejected. Exception: WeChat
                    and Alipay (WE_CHAT / ALIPAY channels) payouts accept the
                    beneficiary's local-script (e.g. Chinese) name.
                accountNumber:
                  type: string
                  description: The account number
                countryCode:
                  type: string
                  description: >-
                    The ISO 3166-1 alpha-2 country code. This has to be one of
                    the countries we support
                institution:
                  $ref: '#/components/schemas/PaymentMethodInstitution'
                  description: >-
                    The destination institution. For USD (SWIFT) payout payment
                    methods, correspondentBankName and
                    correspondentBankAccountNumber are mandatory.
                recipient:
                  $ref: '#/components/schemas/PaymentMethodRecipient'
                transaction:
                  $ref: '#/components/schemas/PaymentMethodTransaction'
            examples:
              Bank Account:
                summary: Bank Account, register a bank account to send funds to
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: BANK_ACCOUNT
                  accountName: John Doe
                  accountNumber: '0123456789'
                  countryCode: NG
                  institution:
                    institutionCode: '058'
                    institutionName: GTBank
              SWIFT Transfer:
                summary: SWIFT, register an international bank account via SWIFT
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: SWIFT
                  accountName: John Doe
                  accountNumber: DE89370400440532013000
                  countryCode: DE
                  institution:
                    institutionCode: DEUTDEDB
                    institutionName: Deutsche Bank
                    institutionAddress: Taunusanlage 12, 60262 Frankfurt am Main, Germany
                    correspondentBankName: Citibank N.A. New York
                    correspondentBankAccountNumber: '10991234'
                  recipient:
                    recipientAddress: Musterstraße 1, 10115 Berlin, Germany
                  transaction:
                    transactionNarration: Payment for services
              Mobile Money:
                summary: Mobile Money, register a mobile money account to send funds to
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: MOBILE_MONEY
                  accountName: John Doe
                  accountNumber: '0201234567'
                  countryCode: GH
                  institution:
                    institutionCode: MTN
                    institutionName: MTN
              Mobile Money (Deposit):
                summary: >-
                  Mobile Money, register a mobile money account to pull funds
                  from
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: DEPOSIT
                  channel: MOBILE_MONEY
                  accountName: John Doe
                  accountNumber: '0201234567'
                  countryCode: GH
                  institution:
                    institutionCode: MTN
                    institutionName: MTN
              UPI:
                summary: UPI, register a UPI ID to send funds to (India)
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: UPI
                  accountName: Raj Kumar
                  accountNumber: rajkumar@upi
                  countryCode: IN
                  institution:
                    institutionCode: UPI
                    institutionName: UPI
                  recipient:
                    recipientPhone: '+919876543210'
              Interac:
                summary: Interac, register an Interac e-Transfer recipient (Canada)
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: INTERAC
                  accountName: John Doe
                  accountNumber: john.doe@email.com
                  countryCode: CA
                  institution:
                    institutionCode: INTERAC
                    institutionName: INTERAC
                  recipient:
                    recipientEmail: john.doe@email.com
              WeChat Pay:
                summary: >-
                  WeChat Pay, register a WeChat Pay account to send funds to
                  (China)
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: WE_CHAT
                  accountName: Zhang Wei
                  accountNumber: '+8613812345678'
                  countryCode: CN
                  institution:
                    institutionCode: WECHAT
                    institutionName: WECHAT
                  recipient:
                    recipientPhone: '+8613812345678'
              Alipay:
                summary: Alipay, register an Alipay account to send funds to (China)
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: ALIPAY
                  accountName: Zhang Wei
                  accountNumber: '+8613812345678'
                  countryCode: CN
                  institution:
                    institutionCode: ALIPAY
                    institutionName: ALIPAY
                  recipient:
                    recipientPhone: '+8613812345678'
              Paybill / Till:
                summary: >-
                  Paybill / Till, register an M-Pesa Paybill or Till number to
                  send funds to (Kenya)
                value:
                  customerId: 69528240ba52c13b669fb239
                  type: WITHDRAW
                  channel: PAYBILL_TILL
                  accountName: Safaricom PLC
                  accountNumber: '174379'
                  countryCode: KE
                  institution:
                    institutionCode: MPESA
                    institutionName: MPESA
      responses:
        '201':
          description: Payment method created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentMethod'
              examples:
                bankAccount:
                  summary: Bank account payment method created
                  value:
                    data:
                      paymentMethodId: 69d6002579101baa20f63816
                      channel: BANK_ACCOUNT
                      customerId: 69d60024ab82306f11b03325
                      institution:
                        institutionCode: '000013'
                        institutionName: GTBank
                      accountName: John Doe
                      accountNumber: '0123456789'
                      countryCode: NG
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingRequiredField:
                  summary: Missing required field
                  value:
                    code: INVALID_USER_DATA
                    error: Invalid user data
                    details:
                      errorMessage: Invalid user data
                      friendlyMessage: ''
        '401':
          description: Unauthorized - Invalid business API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    code: AUTHENTICATION_ERROR
                    error: Authorization header is missing
                    details: {}
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    code: AUTHENTICATION_ERROR
                    error: Invalid authorization header
                    details: {}
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serverError:
                  summary: Unexpected server error
                  value:
                    code: INTERNAL_SERVER_ERROR
                    error: It's not you, it's us, please reach out to support
                    details: {}
      x-codeSamples:
        - lang: TypeScript
          label: Afriex SDK
          source: |
            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",
              },
            });
components:
  parameters:
    x-api-signature:
      name: x-api-signature
      in: header
      required: false
      description: >-
        Signature of the request payload, used for request authentication where
        payload signing is enabled for your business.
      schema:
        type: string
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
        stable.
      schema:
        type: string
  schemas:
    customerId:
      type: string
      description: The unique identifier of the customer.
    PaymentMethodInstitution:
      type: object
      properties:
        institutionId:
          type: string
          description: >-
            The unique identifier of the bank or mobile money provider if
            required.
        institutionName:
          type: string
          description: The name of the bank or mobile money provider if required.
        institutionCode:
          type: string
          description: The code of the bank or mobile money provider.
        institutionAddress:
          type: string
          description: The address of the bank or mobile money provider if required.
        correspondentBankName:
          type: string
          description: >-
            The correspondent (intermediary) bank name. Mandatory for USD
            (SWIFT) payout payment methods; required to produce settlement
            advices/invoices.
        correspondentBankAccountNumber:
          type: string
          description: >-
            The correspondent (intermediary) bank account number. Mandatory for
            USD (SWIFT) payout payment methods; required to produce settlement
            advices/invoices.
    PaymentMethodRecipient:
      type: object
      properties:
        recipientEmail:
          type: string
          format: email
          description: The email address of the recipient if needed.
        recipientPhone:
          type: string
          description: The phone number of the recipient in E.164 format.
        recipientAddress:
          type: string
          description: The address of the recipient if needed.
        recipientName:
          type: string
          description: The name of the recipient if needed.
    PaymentMethodTransaction:
      type: object
      properties:
        transactionInvoice:
          type: string
          description: >-
            The invoice filename (S3 object key) for the transaction, as
            returned by the media upload endpoint.
        transactionNarration:
          type: string
          description: The optional reason for the transaction.
    PaymentMethod:
      type: object
      description: >-
        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.
      properties:
        paymentMethodId:
          type: string
          description: The unique identifier for the payment method.
        customerId:
          $ref: '#/components/schemas/customerId'
        reference:
          type: string
          description: Identifier to reconcile incoming deposits against.
        institution:
          $ref: '#/components/schemas/PaymentMethodInstitution'
        transaction:
          $ref: '#/components/schemas/PaymentMethodTransaction'
        recipient:
          $ref: '#/components/schemas/PaymentMethodRecipient'
        channel:
          type: string
          enum:
            - 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
          description: The payment method channel.
        countryCode:
          type: string
          description: The ISO 3166-1 alpha-2 country code.
        currency:
          type: string
          description: >-
            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:
          type: array
          items:
            type: string
          description: >-
            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:
          type: string
          description: Name of the account holder. Present for account-shaped channels.
        accountNumber:
          type: string
          description: Account number. Present for account-shaped channels.
        routingNumber:
          type: string
          description: >-
            Bank routing number. Present for account-shaped channels that carry
            one (e.g. ACH bank accounts).
        status:
          type: string
          enum:
            - active
            - pending
            - deleted
            - expired
            - blocked
          description: Lifecycle status of the payment method.
        last4:
          type: string
          description: Last 4 digits of the card. CARD channel only.
        brand:
          type: string
          enum:
            - Visa
            - MasterCard
            - Discover
            - American Express
            - JCB
            - Diners Club
            - Eftpos Australia
            - UnionPay
            - Unknown
          description: Card brand. CARD channel only.
        expiration:
          type: object
          description: Card expiration. CARD channel only.
          properties:
            month:
              type: integer
            year:
              type: integer
        cardName:
          type: string
          description: Name on the card. CARD channel only.
        expiresInMinutes:
          type: integer
          description: Minutes until a dynamic virtual account expires, when applicable.
        amount:
          type: number
          description: Requested amount for a dynamic virtual account, when applicable.
        extra:
          type: object
          description: Additional channel-specific properties.
          additionalProperties: true
        meta:
          type: object
          description: Optional meta data you attached to the payment method.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        errorMessage:
          type: string
          description: Detailed/technical error message.
        friendlyMessage:
          type: string
          description: User-facing error message safe to display.
        data:
          type: object
          description: >-
            Optional caller-safe context for the error. On a customer-create
            uniqueness conflict (EMAIL_ALREADY_EXISTS /
            PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
            id, so you can adopt it without a follow-up lookup.
          properties:
            customerId:
              type: string
              description: Id of the existing customer (on a create conflict).
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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. Requests made with a key that does not
        include the permission required by the target endpoint will be rejected
        with a `403 Forbidden` response; an unrecognised, malformed or revoked
        key returns `401 Unauthorized`. Manage your keys and their permissions
        under **Developer → API keys** in the dashboard.

````