Initiate a bulk VA transfer when a single payout amount needs to be split into multiple provider payouts.

Kyshi calculates the transfer fee once on the full amount, reserves the total debit once, creates a batch, and processes each provider payout in the background. This is useful when the provider payout limit is lower than the amount you need to send.

You can use an existing beneficiaryId, or provide a beneficiary object and Kyshi will find or create the beneficiary during initiation.

-H "x-api-key: your_secret_key"
-H "idempotency-key: unique-bulk-transfer-key"

POST {{host}}/v1/va/transfer/bulk

Request Body

Field	Data Type	Required	Description
beneficiaryId	string	Yes, if `beneficiary` is not supplied	Existing VA beneficiary ID.
beneficiary	object	Yes, if `beneficiaryId` is not supplied	Beneficiary details. Use the same fields as Create VA Beneficiary.
currency	string	Yes	Use `NGN`.
amount	number	Yes	Total amount to transfer in NGN.
narration	string	Yes	Batch narration.
splitCount	number	No	Number of provider payouts to create. If omitted, Kyshi auto-splits by the provider payout limit. Minimum `1`, maximum `200`.

{
  "beneficiaryId": "8495ec4e-ce21-405f-b0cf-982702881f4d",
  "currency": "NGN",
  "amount": 100000000,
  "narration": "Bulk supplier payout",
  "splitCount": 20
}

If the API call is successful, Kyshi returns the batch and its child payout items.

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "id": "0e7c4f6d-6d5c-46b7-91fd-91d7f100a001",
    "reference": "BULK-1778623597453",
    "status": "PROCESSING",
    "currency": "NGN",
    "mode": "live",
    "provider": "VFD",
    "rail": "VFD_VA",
    "amount": 100000000,
    "totalFees": 100,
    "totalDebitAmount": 100000100,
    "splitCount": 20,
    "successfulCount": 0,
    "failedCount": 0,
    "pendingCount": 20,
    "beneficiary": {
      "id": "8495ec4e-ce21-405f-b0cf-982702881f4d",
      "accountName": "FEMI ZACK",
      "accountNumber": "0123456789",
      "bankCode": "000014"
    },
    "items": [
      {
        "id": "c5c5ed7c-7d86-45b6-a240-f21a5d000001",
        "sequence": 1,
        "reference": "BULK-1778623597453-001",
        "amount": 5000000,
        "status": "PENDING"
      }
    ]
  }
}

Notes

The total amount debited is the full batch amount plus one totalFees value.
Kyshi auto-splits by the provider payout limit when splitCount is not supplied.
For a NGN 100,000,000 batch with a NGN 5,000,000 provider limit, use splitCount: 20 or omit splitCount and let Kyshi calculate it.
Use GET /v1/va/transfer/bulk/{id} to retrieve the latest batch and item statuses.
Kyshi returns Insufficient Funds if your available balance cannot cover the full amount and fees.