Sign in

Payments

How to run bulk charges

View as Markdown

In a nutshell

Queue and monitor many authorization-based charges in a single bulk charge batch.

Copy linkPrepare the batch

Build an array of charge objects. Each object can include:

  • amount (required)
  • authorization (required)
  • reference (recommended)
  • attempt_partial_debit
  • at_least
  • metadata

Paystack’s bulk charge guide recommends passing a unique reference for each charge for tracking and idempotency.

Copy linkKeep the batch within limits

Use these limits when building the batch:

  • maximum batch size: 1000
  • retry limit per charge: 5

Copy linkInitiate the batch

Send the charge objects to https://api.paystack.co/bulkcharge.

curl https://api.paystack.co/bulkcharge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '[
  {
    "amount": 10000,
    "authorization": "AUTH_ncx8hews93",
    "reference": "my_reference_1"
  },
  {
    "amount": 15000,
    "authorization": "AUTH_200nvt70zo",
    "reference": "my_reference_2"
  },
  {
    "amount": 25000,
    "authorization": "AUTH_84bqxd3rkf",
    "reference": "my_reference_3"
  }
]' \
-X POST

A successful response returns the batch metadata:

{
  "status": true,
  "message": "Charges have been queued",
  "data": {
    "batch_code": "BCH_ml3zk2hregr1inj",
    "status": "active",
    "total_charges": 3,
    "pending_charges": 3
  }
}

Save the batch_code.

Copy linkTrack each charge

Bulk charge processing is queued and asynchronous. Paystack sends a webhook event for each successful charge in the batch.

{
  "event": "charge.success",
  "data": {
    "reference": "my_reference_3",
    "amount": 25126,
    "requested_amount": 25000,
    "metadata": {
      "custom_fields": [
        {
          "display_name": "Bulkcharge batch code",
          "variable_name": "bulkcharge_batch_code",
          "value": "BCH_ml3zk2hregr1inj"
        }
      ]
    }
  }
}

Process webhook events per charge reference, not only per batch.

Copy linkHandle retries and exceptions

If a charge does not produce a success webhook, verify it manually before retrying. Use gateway_response to separate customer failures from processing failures. Reuse the same reference only when you intentionally want idempotent retry behavior.

If your business accepts lower fallback collections, include attempt_partial_debit and at_least in each charge object.

Was this page helpful?