Payments
How to run bulk charges
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_debitat_leastmetadata
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.