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. Disbursements (Transfers)
  3. Batch Disbursements

Initiate A Disbursement

Initiate a disbursement containing the list of bank and inter-merchant transfers.

PreviousBatch DisbursementsNextList Batch Transfers

Last updated 6 months ago

Transfer to bank accounts

Transfer to both banks and gateway merchants

  • Transfer to bank accounts
  • POST/v1/transfers/bank
  • Transfer to both banks and gateway merchants
  • POST/v1/transfers
post
Authorizations
Body
pinstring | nullableOptional
batch_referencestring | nullableOptional
source_currencystring | nullableOptional
scheduled_datestring · date-time | nullableOptional
break_on_validation_failurebooleanOptional
batch_webhook_typestring · enumOptional

This determines how the webhooks are called for batch transfers

Possible values:
batch_notification_intervalstring · enumOptional

This determines the sequence of updates for batch transfers if batch webhooks are enabled

Possible values:
titlestring | nullableOptional
descriptionstring | nullableOptional
Responses
200
Success
application/json
post
POST /v1/transfers HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1151

{
  "pin": "text",
  "batch_reference": "text",
  "source_currency": "text",
  "scheduled_date": "2025-05-20T16:48:20.997Z",
  "break_on_validation_failure": true,
  "batch_webhook_type": "batchOnly",
  "batch_notification_interval": "tenPercent",
  "title": "text",
  "description": "text",
  "transfers": [
    {
      "reference": "text",
      "description": "text",
      "beneficiary_id": "text",
      "save_as_beneficiary": true,
      "country": "text",
      "currency": "text",
      "amount": 1,
      "wallet_account_tags": [
        {
          "account_tag": "text",
          "amount": 1,
          "description": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          }
        }
      ],
      "account_number": "text",
      "account_name": "text",
      "bank_name": "text",
      "bank_code": "text",
      "sort_code": "text",
      "swift_code": "text",
      "email": "text",
      "phone_number": "text",
      "street_number": "text",
      "street_name": "text",
      "city": "text",
      "postal_code": "text"
    }
  ],
  "gateway_transfers": [
    {
      "reference": "text",
      "description": "text",
      "beneficiary_id": "text",
      "save_as_beneficiary": true,
      "country": "text",
      "currency": "text",
      "amount": 1,
      "wallet_account_tags": [
        {
          "account_tag": "text",
          "amount": 1,
          "description": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          }
        }
      ],
      "merchant_id_or_code": "text",
      "recipient_gateway_code": "text"
    }
  ]
}
200

Success

{
  "id": "text",
  "is_live": true,
  "batch_reference": "text",
  "source_currency": "text",
  "break_on_validation_failure": true,
  "two_factor_enabled": true,
  "otp_sent": true,
  "otp_expires_at": "2025-05-20T16:48:20.997Z",
  "otp_validated": true,
  "otp_validated_at": "2025-05-20T16:48:20.997Z",
  "bank_transfers_count": 1,
  "gateway_transfers_count": 1,
  "total_count": 1,
  "failed_count": 1,
  "successful_count": 1,
  "total_amount": 1,
  "total_successful_amount": 1,
  "total_fee": 1,
  "batch_webhook_type": "batchOnly",
  "batch_notification_interval": "tenPercent",
  "title": "text",
  "description": "text",
  "status": "allSuccessful",
  "created_at": "2025-05-20T16:48:20.997Z",
  "edited_at": "2025-05-20T16:48:20.997Z"
}
post
Authorizations
Body
batch_referencestring | nullableOptional
source_currencystring | nullableOptional
scheduled_datestring · date-time | nullableOptional
break_on_validation_failurebooleanOptional
batch_webhook_typestring · enumOptional

This determines how the webhooks are called for batch transfers

Possible values:
batch_notification_intervalstring · enumOptional

This determines the sequence of updates for batch transfers if batch webhooks are enabled

Possible values:
titlestring | nullableOptional
descriptionstring | nullableOptional
Responses
200
Success
application/json
post
POST /v1/transfers/bank HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 579

{
  "batch_reference": "text",
  "source_currency": "text",
  "scheduled_date": "2025-05-20T16:48:20.997Z",
  "break_on_validation_failure": true,
  "batch_webhook_type": "batchOnly",
  "batch_notification_interval": "tenPercent",
  "title": "text",
  "description": "text",
  "transfers": [
    {
      "reference": "text",
      "description": "text",
      "beneficiary_id": "text",
      "save_as_beneficiary": true,
      "currency": "text",
      "amount": 1,
      "wallet_account_tags": [
        {
          "account_tag": "text",
          "amount": 1,
          "description": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          }
        }
      ],
      "country": "text",
      "account_number": "text",
      "bank_code": "text"
    }
  ]
}
200

Success

{
  "id": "text",
  "is_live": true,
  "batch_reference": "text",
  "source_currency": "text",
  "break_on_validation_failure": true,
  "two_factor_enabled": true,
  "otp_sent": true,
  "otp_expires_at": "2025-05-20T16:48:20.997Z",
  "otp_validated": true,
  "otp_validated_at": "2025-05-20T16:48:20.997Z",
  "total_count": 1,
  "failed_count": 1,
  "successful_count": 1,
  "total_amount": 1,
  "total_successful_amount": 1,
  "total_fee": 1,
  "batch_webhook_type": "batchOnly",
  "batch_notification_interval": "tenPercent",
  "title": "text",
  "description": "text",
  "status": "allSuccessful",
  "created_at": "2025-05-20T16:48:20.997Z",
  "edited_at": "2025-05-20T16:48:20.997Z"
}