Skip to content

Bulk Sub-Wallet Transfers

Fund multiple of your business's own issued (sub) wallets in a single request by uploading a CSV file.

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

cURL Example

curl --location 'https://core-sandbox.payonus.com/api/v1/transfer-requests/bulk/sub-wallet-transfer' \
--header 'Authorization: Bearer xxxxxxxxxxxxxx' \
--form 'file=@"/Users/user/Downloads/bulk_sub_wallet_transfer_template.csv"' \
--form 'description="Payroll wallet top-up"' \
--form 'reference="ONUS-SUBWTRNF-BLK-20250101-001"' \
--form 'businessId="xxx-xxx-xxx"' \
--form 'walletId="xxx-xxx-xxx"' \
--form 'countryCode="NG"' \
--form 'currency="NGN"' \
--form 'notificationUrl=""'

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). Must own every sub wallet referenced in the CSV.
  • walletId (required): The ID of your own business wallet to debit. A business can hold multiple wallets, so this must always be specified explicitly — there is no automatic fallback.
  • countryCode (required): ISO-2 country code, e.g., NG.
  • currency (required): ISO-3 currency code, e.g., NGN. Must match the currency of every sub wallet referenced in the CSV.
  • file (required): CSV file containing the list of sub-wallet transfers.
  • description (optional): Description of the bulk transfer batch.
  • notificationUrl (optional): Callback URL for notifications.

CSV File Format

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

Expected columns (header row):

WalletReference,Amount,Email,Narration
  • WalletReference: The reference you assigned to the sub wallet when you created it. Identifies which of your own sub wallets receives the funds for that row.
  • Amount: Transfer amount (base unit, e.g., 500 → 500 NGN).
  • Email: Notification email for the row (optional per row).
  • Narration: Per-row description or note for the transfer.

Every row funds a sub wallet owned by businessId, debited from the wallet identified by walletId. You can include as many rows as you like — wallet lookups are batched internally, so large files are processed efficiently. Do not remove the header row.

Response

The API will return the following information:

Field Type Description
message string Success when the batch has been accepted and queued for processing 
{
  "status": 200,
  "message": "Success",
  "data": {
    "message": "Success"
  }
}

Notes

  • Idempotency: Use a distinct reference per bulk upload to prevent duplicates.
  • Each WalletReference must belong to businessId and must not have been deleted — if any row's reference can't be resolved, the entire batch is rejected (nothing is created).
  • Each sub wallet's currency must match the request currency.
  • Validation: The request will fail if required form fields are missing or the CSV does not conform to the expected format.