SwitchApp API
  • Introduction
  • Quick Start
  • Authentication
  • Errors
  • Metadata
  • Pagination
  • Versioning
  • No-code solutions
  • Webhooks
  • Payments
    • Transactions
      • Initialize a transaction
      • Verify transaction
      • List transactions
      • Retrieve Transaction
      • Transaction Webhooks
  • Payment Providers
    • Payment Providers
  • Countries & Currencies
    • Countries
    • Currencies
  • Products
    • Products
      • Create a product
      • Retrieve a product
      • Update a product
      • List all products
      • Delete a product
  • Customers
    • Customers
      • Create Customer
      • List Customers
      • Fetch Customer
      • Update Customer
      • Delete/Archive Customer
  • Payment Links
    • Payment Links
      • Create a payment link
      • Fetch payment link
      • Update a payment link
      • List all payment links
      • Delete a payment link
  • Payouts
    • Payouts
      • List Payouts
      • Fetch Payout
      • Retry Payout
  • BALANCES
    • Balances
      • Fetch all balances
      • Fetch a balance
      • Fetch currency balance
  • DISBURSEMENTS
    • Disbursements (Transfers)
      • Batch Disbursements
        • Initiate A Disbursement
        • List Batch Transfers
        • Fetch A Batch
        • Requeue All Failed Transfers
      • Single Disbursements
        • Fetch List By Batch Reference
        • Fetch All Singles By Page
        • Fetch A Single Disbursement
        • Fetch fee
        • Fetch rate
    • Beneficiaries
      • Create a beneficiary
      • List all beneficiaries
      • Fetch a beneficiary
      • Delete a beneficiary
    • Banks
      • Bank list
      • Bank slugs
      • Resolve account details
  • VIRTUAL ACCOUNTS
    • Virtual Accounts
      • Top-up virtual accounts
        • Fetch providers
        • Create top-up account
        • List accounts
        • Fetch account
        • Requery account
        • Deallocate account
      • Payment virtual accounts
        • Fetch providers
        • Create payment account
        • Update account details
        • List accounts
        • Fetch account
        • Requery account
        • Deallocate account
Powered by GitBook
On this page
  1. DISBURSEMENTS
  2. Beneficiaries

Create a beneficiary

PreviousBeneficiariesNextList all beneficiaries

Last updated 6 months ago

Create a beneficiary using the recipient's bank details.

You can also specify other details including an alias for the beneficiary (i.e. an easy-to-remember name different from the account name.)

  • POSTCreate a bank beneficiary for bank transfers
  • POSTCreate a beneficiary for transfers b/w merchants or across payment gateways

Create a bank beneficiary for bank transfers

post
Authorizations
Body
currencystring | nullableOptional
countrystring | nullableOptional
full_namestring | nullableOptional
emailstring | nullableOptional
phone_numberstring | nullableOptional
descriptionstring | nullableOptional
account_numberstring | nullableOptional
bank_codestring | nullableOptional
bank_namestring | nullableOptional
account_namestring | nullableOptional
street_numberstring | nullableOptional
street_namestring | nullableOptional
citystring | nullableOptional
postal_codestring | nullableOptional
Responses
200
Success
application/json
post
POST /v1/beneficiaries/create/bank-transfer HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 276

{
  "currency": "text",
  "country": "text",
  "full_name": "text",
  "email": "text",
  "phone_number": "text",
  "description": "text",
  "account_number": "text",
  "bank_code": "text",
  "bank_name": "text",
  "account_name": "text",
  "street_number": "text",
  "street_name": "text",
  "city": "text",
  "postal_code": "text"
}
200

Success

{
  "status": "success",
  "message": "text",
  "data": {
    "id": "text",
    "beneficiary_type": "bankAccount",
    "currency": "text",
    "country": "text",
    "full_name": "text",
    "email": "text",
    "phone_number": "text",
    "description": "text",
    "account_number": "text",
    "account_name": "text",
    "bank_name": "text",
    "bank_code": "text",
    "created_at": "2025-05-20T13:44:54.783Z",
    "edited_at": "2025-05-20T13:44:54.783Z"
  },
  "meta": {},
  "errors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "is_error": true
}

Create a beneficiary for transfers b/w merchants or across payment gateways

post
Authorizations
Body
currencystring | nullableOptional
countrystring | nullableOptional
full_namestring | nullableOptional
emailstring | nullableOptional
phone_numberstring | nullableOptional
descriptionstring | nullableOptional
merchant_id_or_codestring | nullableOptional
recipient_gateway_codestring | nullableOptional
Responses
200
Success
application/json
post
POST /v1/beneficiaries/create/gateway-transfer HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "currency": "text",
  "country": "text",
  "full_name": "text",
  "email": "text",
  "phone_number": "text",
  "description": "text",
  "merchant_id_or_code": "text",
  "recipient_gateway_code": "text"
}
200

Success

{
  "status": "success",
  "message": "text",
  "data": {
    "id": "text",
    "beneficiary_type": "bankAccount",
    "currency": "text",
    "country": "text",
    "full_name": "text",
    "email": "text",
    "phone_number": "text",
    "description": "text",
    "account_number": "text",
    "account_name": "text",
    "bank_name": "text",
    "bank_code": "text",
    "created_at": "2025-05-20T13:44:54.783Z",
    "edited_at": "2025-05-20T13:44:54.783Z"
  },
  "meta": {},
  "errors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "is_error": true
}