Bulk Charge

A collection of endpoints for creating and managing multiple recurring payments

Copy link List Bulk Charge Batches

List all bulk charge batches.

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The offset to retrieve data from
statusstring
Filter by the status of the charges
Enumactivepausedcomplete

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredstring
pagerequiredinteger
pageCountrequiredinteger
GET/bulkcharge
curl https://api.paystack.co/bulkcharge \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.list({
  perPage: 100,
  page: 100
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.list({
  per_page: 100,
  page: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Bulk charges retrieved",
  "data": [
    {
      "domain": "test",
      "batch_code": "BCH_1nV4L1D7cayggh",
      "status": "complete",
      "id": 1733,
      "createdAt": "2017-02-04T05:44:19.000Z",
      "updatedAt": "2017-02-04T05:45:02.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Initiate Bulk Charge

Charge multiple customers in batches

Request Body

itemsarray[object]

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
10 object properties
batch_coderequiredstring
referencerequiredstring
idrequiredinteger
integrationrequiredinteger
domainrequiredstring
statusrequiredstring
total_chargesrequiredinteger
pending_chargesrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
POST/bulkcharge
curl https://api.paystack.co/bulkcharge \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": []
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.initiate({
  items: []
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.initiate({
  items: []
})
puts response.data
Response
{
  "status": true,
  "message": "Charges have been queued",
  "data": {
    "batch_code": "BCH_rrsbgwb4ivgzst1",
    "reference": "bulkcharge-1663150565684-p18nyoa68a",
    "id": 66608171,
    "integration": 463433,
    "domain": "test",
    "status": "active",
    "total_charges": 2,
    "pending_charges": 2,
    "createdAt": "2022-09-14T10:16:05.000Z",
    "updatedAt": "2022-09-14T10:16:05.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Bulk Charge Batch

This endpoint retrieves a specific batch code. It also returns useful information on its progress by way of the `total_charges` and `pending_charges` attributes.

Path Parameters

coderequiredstring
The code for the charge whose batches you want to retrieve

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
10 object properties
batch_coderequiredstring
referencerequiredstring
idrequiredinteger
integrationrequiredinteger
domainrequiredstring
statusrequiredstring
total_chargesrequiredinteger
pending_chargesrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
GET/bulkcharge/{code}
curl https://api.paystack.co/bulkcharge/BCH_180tl7oq7cayggh \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.fetch("BCH_180tl7oq7cayggh");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.fetch("BCH_180tl7oq7cayggh")
puts response.data
Response
{
  "status": true,
  "message": "Bulk charge retrieved",
  "data": {
    "domain": "test",
    "batch_code": "BCH_180tl7oq7cayggh",
    "status": "complete",
    "id": 17,
    "total_charges": 0,
    "pending_charges": 0,
    "createdAt": "2017-02-04T05:44:19.000Z",
    "updatedAt": "2017-02-04T05:45:02.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link List Charges in a Batch

This endpoint retrieves the charges associated with a specified batch code

Path Parameters

coderequiredstring
An code for the batch whose charges you want to retrieve

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The offset to retrieve data from
statusstring
Filter by the status of the charges
Enumsuccessfailedpendingerrorinactive_authorization

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
perPagerequiredstring
totalrequiredinteger
skippedrequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/bulkcharge/{code}/charges
curl https://api.paystack.co/bulkcharge/BCH_180tl7oq7cayggh/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.charges("BCH_180tl7oq7cayggh", {
  perPage: 100,
  page: 100
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.charges("BCH_180tl7oq7cayggh", {
  per_page: 100,
  page: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Bulk charge items retrieved",
  "data": [
    {
      "integration": 100073,
      "bulkcharge": 18,
      "customer": {
        "id": 181336,
        "first_name": null,
        "last_name": null,
        "email": "[email protected]",
        "customer_code": "CUS_dw5posshfd1i5uj",
        "phone": null,
        "metadata": null,
        "risk_action": "default"
      },
      "authorization": {
        "authorization_code": "AUTH_jh3cfpca",
        "bin": "412345",
        "last4": "1381",
        "exp_month": "08",
        "exp_year": "2088",
        "channel": "card",
        "card_type": "visa visa",
        "bank": "TEST BANK",
        "country_code": "NG",
        "brand": "visa",
        "reusable": true,
        "account_name": "BoJack Horseman"
      },
      "transaction": {
        "id": 718835,
        "domain": "test",
        "status": "success",
        "reference": "2mr588n0ik9enja",
        "amount": 20500,
        "message": null,
        "gateway_response": "Successful",
        "paid_at": "2017-02-04T06:05:02.000Z",
        "created_at": "2017-02-04T06:05:02.000Z",
        "channel": "card",
        "currency": "NGN",
        "ip_address": null,
        "metadata": "",
        "log": null,
        "fees": null,
        "fees_split": null,
        "customer": {},
        "authorization": {},
        "plan": {},
        "subaccount": {},
        "paidAt": "2017-02-04T06:05:02.000Z",
        "createdAt": "2017-02-04T06:05:02.000Z"
      },
      "domain": "test",
      "amount": 20500,
      "currency": "NGN",
      "status": "success",
      "id": 15,
      "createdAt": "2017-02-04T06:04:26.000Z",
      "updatedAt": "2017-02-04T06:05:03.000Z"
    },
    {
      "integration": 100073,
      "bulkcharge": 18,
      "customer": {
        "id": 181336,
        "first_name": null,
        "last_name": null,
        "email": "[email protected]",
        "customer_code": "CUS_dw5posshfd1i5uj",
        "phone": null,
        "metadata": null,
        "risk_action": "default"
      },
      "authorization": {
        "authorization_code": "AUTH_qdyfjbl3",
        "bin": "412345",
        "last4": "1381",
        "exp_month": "08",
        "exp_year": "2018",
        "channel": "card",
        "card_type": "visa visa",
        "bank": "TEST BANK",
        "country_code": "NG",
        "brand": "visa",
        "reusable": true,
        "account_name": "BoJack Horseman"
      },
      "transaction": {
        "id": 718836,
        "domain": "test",
        "status": "success",
        "reference": "5xkmvfe2h4065zl",
        "amount": 11500,
        "message": null,
        "gateway_response": "Successful",
        "paid_at": "2017-02-04T06:05:02.000Z",
        "created_at": "2017-02-04T06:05:02.000Z",
        "channel": "card",
        "currency": "NGN",
        "ip_address": null,
        "metadata": "",
        "log": null,
        "fees": null,
        "fees_split": null,
        "customer": {},
        "authorization": {},
        "plan": {},
        "subaccount": {},
        "paidAt": "2017-02-04T06:05:02.000Z",
        "createdAt": "2017-02-04T06:05:02.000Z"
      },
      "domain": "test",
      "amount": 11500,
      "currency": "NGN",
      "status": "success",
      "id": 16,
      "createdAt": "2017-02-04T06:04:26.000Z",
      "updatedAt": "2017-02-04T06:05:03.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Pause Bulk Charge Batch

Pause the processing of a charge batch

Path Parameters

coderequiredstring
The batch code for the bulk charge you want to pause

Response

200
statusrequiredboolean
messagerequiredstring
GET/bulkcharge/pause/{code}
curl https://api.paystack.co/bulkcharge/pause/BCH_180tl7oq7cayggh \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.pause("BCH_180tl7oq7cayggh");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.pause("BCH_180tl7oq7cayggh")
puts response.data
Response
{
  "status": true,
  "message": "Bulk charge batch has been paused"
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Resume Bulk Charge Batch

Resume the processing of a previously paused charge batch

Path Parameters

coderequiredstring
The batch code for the bulk charge you want to pause

Response

200
statusrequiredboolean
messagerequiredstring
GET/bulkcharge/resume/{code}
curl https://api.paystack.co/bulkcharge/resume/BCH_180tl7oq7cayggh \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.bulkCharge.resume("BCH_180tl7oq7cayggh");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.bulk_charge.resume("BCH_180tl7oq7cayggh")
puts response.data
Response
{
  "status": true,
  "message": "Bulk charge batch has been resumed"
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}