PayoutsRecipient Types

Bank Transfers

Send payouts to bank accounts

Use the Payouts API to send funds to recipient bank accounts. Set paymentMethodId to "banktransfer" and provide a recipient object with type: "bank_account".

Request Shape

Set paymentMethodId to "banktransfer" and provide recipient with the following structure:

FieldRequiredDescription
typeYesMust be "bank_account"
accountNumberYesThe recipient’s bank account number. Format may vary by country (see format notes below).
bankCodeYesBank identifier code (e.g., sort code, routing number).
accountHolderNameYesName on the bank account.
countryYes3-letter ISO country code (e.g., NGA, EGY).
phoneNumberNoPhone number in international format (optional).

Top-level required fields for every payout:

  • Required: merchantId, merchantReference, destinationValue (with minorAmount and currency), paymentMethodId ("banktransfer"), paymentLocation, recipient, sender (with fullName, identity, identityNumber)
  • Optional: attributes

Example Request

{
  "merchantId": "your-merchant-id",
  "merchantReference": "PAYOUT-2024-001",
  "destinationValue": {
    "minorAmount": 1000000,
    "currency": "NGN"
  },
  "paymentMethodId": "banktransfer",
  "paymentLocation": "NGA",
  "recipient": {
    "type": "bank_account",
    "accountNumber": "0123456789",
    "bankCode": "044",
    "accountHolderName": "John Doe",
    "country": "NGA"
  },
  "sender": {
    "fullName": "Jane Smith",
    "identity": "passport",
    "identityNumber": "A12345678"
  },
  "attributes": {}
}

Note: minorAmount: 1000000 = 10,000.00 NGN (NGN has 2 decimal places).

Required vs Optional Summary

  • Required for recipient (bank_account): type ("bank_account"), accountNumber, bankCode, accountHolderName, country
  • Optional for recipient: phoneNumber
  • Required at request level: merchantId, merchantReference, destinationValue, paymentMethodId, paymentLocation, recipient, sender (with fullName, identity, identityNumber)
  • Optional at request level: attributes

The API reference is the source of truth for the schema.

Format and Validation Notes

The authoritative list of banks and their codes for a country comes from GET /v1/payout/banks?country={ISO3} — it returns {banks: [{code, name}]} straight from the processors, so it never drifts. Use it to populate bank pickers.

  • Nigeria (NGN): Account numbers are typically 10 digits. bankCode is the bank identifier code — fetch the live list via GET /v1/payout/banks?country=NGA, or see Nigeria Bank Codes for a reference list.
  • South Africa (ZAR): Use the bank’s 6-digit universal (any-branch) code (e.g. 632005 for Absa). See South Africa for the full list of valid bankCode values. Account numbers are 9–13 digits.
  • Egypt (EGP): Account number format as required by the local rail; IBAN is supported and required for some banks (e.g. USD transfers). bankCode is required. Valid bank codes include BDC, CIB, POST; see Egypt for details. Egypt typically needs additional sender fields—see Egypt and the API reference.
  • Other currencies: Use the account number and bank code formats accepted by the local clearing system. The bankCode field is required for all bank transfers.

Amount Format: Amounts are specified in minor units (integer), per the currency’s ISO 4217 exponent — for example, minorAmount: 1000000 = 10,000.00 NGN, while zero-decimal currencies like XOF and XAF need no conversion. See Single Payouts for details.

Where Bank Transfers Are Supported

Not every currency supports bank payouts. See Supported Destinations for a table of currencies, countries, and supported rails (bank vs mobile wallet).

Next Steps