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 4 months ago

Transfer to bank accounts

Transfer to both banks and gateway merchants

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

Available options:
batch_notification_intervalstring · enumoptional

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

Available options:
titlestring | nullableoptional
descriptionstring | nullableoptional
transfersobject[] | nullableoptional

gateway_transfersobject[] | nullableoptional

Responses
application/json
cURL
JavaScript
Python
HTTP
curl -L \
  --request POST \
  --url '/v1/transfers' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pin": "text",
    "batch_reference": "text",
    "source_currency": "text",
    "scheduled_date": "2025-04-03T10:34:10.642Z",
    "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
{
  "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-04-03T10:34:10.642Z",
  "otp_validated": true,
  "otp_validated_at": "2025-04-03T10:34:10.642Z",
  "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-04-03T10:34:10.642Z",
  "edited_at": "2025-04-03T10:34:10.642Z"
}

Success

  • Transfer to bank accounts
  • POST/v1/transfers/bank
  • Transfer to both banks and gateway merchants
  • POST/v1/transfers
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

Available options:
batch_notification_intervalstring · enumoptional

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

Available options:
titlestring | nullableoptional
descriptionstring | nullableoptional
transfersobject[] | nullableoptional

Responses
application/json
cURL
JavaScript
Python
HTTP
curl -L \
  --request POST \
  --url '/v1/transfers/bank' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "batch_reference": "text",
    "source_currency": "text",
    "scheduled_date": "2025-04-03T10:34:10.642Z",
    "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
{
  "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-04-03T10:34:10.642Z",
  "otp_validated": true,
  "otp_validated_at": "2025-04-03T10:34:10.642Z",
  "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-04-03T10:34:10.642Z",
  "edited_at": "2025-04-03T10:34:10.642Z"
}

Success