DevelopersPayoutBulk Payout

Bulk Payout

Initiates a bulk payout from a publicly accessible CSV file.

POST{{base_url}}/request/payout/bulk-payout

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "reference": "seamless-ref-bulk-01",
  "file": "https://stkongapaysharedxftn.blob.core.windows.net/kongapay/bulkpayout/bulk-payout-sample.csv"
}

Request Fields

Field	Required	Description
reference	Yes	Unique bulk transaction reference.
file	Yes	Publicly accessible CSV file URL containing payout rows.

CSV Format

The uploaded CSV file must contain payout records in the following format:

csv

Account Name,Account Number,Bank Code,Amount,Comment
IFEANYI OKERE,10000000702,999999,10,Single Payout
Music Fav,1001698487,999999,1100,Single Payout

CSV Field Definitions

Column	Description
Account Name	Beneficiary account name.
Account Number	Beneficiary account number.
Bank Code	Beneficiary bank or institution code.
Amount	Transfer amount in NGN.
Comment	Transaction narration.

Sample Success Response

{
  "id": 329,
  "transaction_type_id": 6,
  "amount": "90000.00",
  "reference": "SHQ-Payout:j_paQXDtPz6MwUg",
  "account": "1000572816",
  "user": "[email protected]",
  "status": "success",
  "created_at": "2024-04-14T08:47:14.447Z",
  "updated_at": "2024-06-25T05:24:02.000Z",
  "processes": [
    {
      "processor": "Knip",
      "status": "success",
      "amount": "40000.00",
      "receipt": "KP-JeM37-1713081024-pro"
    },
    {
      "processor": "Knip",
      "status": "success",
      "amount": "50000.00",
      "receipt": "KP-udy0F-1713081045-pro"
    }
  ],
  "type": {
    "name": "Bulk Payout",
    "contract": "transfer",
    "code": "BPA"
  }
}

ℹ️

The actual response contains additional metadata, including internal references, timestamps, validation information, TSQ responses, and processor payloads.

Transaction Statuses

These are the possible parent transaction statuses returned on the top-level status field.

Status	Meaning
pending	Transaction has been created but is still awaiting approval, validation, or execution. For bulk payouts, this may indicate that one or more payout rows are still pending.
ready	All required approvals have been completed and the transaction is ready for execution. This is typically a short-lived internal state.
processing	Transaction execution has started and one or more payout rows are being processed.
success	All payout rows completed successfully.
failed	All payout rows failed.
incomplete	The bulk payout completed with mixed outcomes. Some rows succeeded while others failed or were cancelled.
cancelled	The transaction, or all payout rows, were cancelled before completion.

Bulk Payout Row Statuses

Each item within the processes array has its own execution status.

Status	Meaning
pending	This payout row has not started execution yet.
queued	This payout row has been queued for execution.
processing	This payout row is currently being processed.
confirming	The payout row has been sent to the processor and is awaiting final confirmation or status query.
acknowledged	The processor has acknowledged receipt, but final status has not yet been determined.
success	The payout row completed successfully.
failed	The payout row failed.
cancelled	The payout row was cancelled before completion.

Important Notes

⚠️

For bulk payouts, always inspect both the top-level status field and the individual processes[].status values.

Example

If the parent transaction status is:

json

{
  "status": "incomplete"
}

Inspect each entry in processes to determine which payout rows succeeded, failed, or were cancelled. This provides the complete execution outcome for the bulk payout request.

← PreviousSingle Payout

Next →Get Transaction Status