Skip to content

Bulk Bank Transfers

Create multiple bank transfers in a single request by uploading a CSV file.

  • Endpoint: POST /api/v1/transfer-requests/bulk/bank-transfer
  • Content-Type: multipart/form-data

cURL Example

curl --location 'https://core-sandbox.payonus.com/api/v1/transfer-requests/bulk/bank-transfer' \
--header 'Authorization: Bearer xxxxxxxxxxxxxx' \
--form 'file=@"/Users/user/Downloads/bulk_transfer_template.csv"' \
--form 'description="Test Bulk Transfer"' \
--form 'reference="ONUS-TRNF-BLK-20250101-001"' \
--form 'businessId="xxx-xxx-xxx"' \
--form 'transferType="WALLET_TO_BANK_ACCOUNT"' \
--form 'countryCode="NG"' \
--form 'currency="NGN"' \
--form 'notificationUrl=""' \
--form 'momoNetwork=""'

Request Fields

The following multipart form fields are supported. Items marked as required must be provided.

  • reference (required): A unique reference for the bulk job for idempotency and reconciliation.
  • businessId (required): Your business identifier (UUID).
  • transferType (required): Transfer type, e.g., WALLET_TO_BANK_ACCOUNT or WALLET_TO_MOMO.
  • countryCode (required): ISO-2 country code, e.g., NG.
  • currency (required): ISO-3 currency code, e.g., NGN.
  • file (required): CSV file containing the list of transfers.
  • description (optional): Description of the bulk transfer batch.
  • notificationUrl (optional): Callback URL for notifications.
  • momoNetwork (optional): Mobile money network if applicable.

CSV File Format

Download the CSV template and populate it with your transfer rows:

Expected columns (header row):

name,account,bank code,amount,email,desc
  • name: Beneficiary name.
  • account: Beneficiary bank account number.
  • bank code: Destination bank code (as supported by the platform).
  • amount: Transfer amount (in the smallest unit or base unit as configured; typically base unit, e.g., 500 → 500 NGN).
  • email: Beneficiary email (optional, used for notifications if supported).
  • desc: Per-row description or note for the transfer.

Ensure each subsequent row represents a single transfer. Do not remove the header.

Notes

  • Idempotency: Use a distinct reference per bulk upload to prevent duplicates.
  • Validation: The request will fail if required form fields are missing or the CSV does not conform to the expected format.