Plan

A collection of endpoints for creating and managing recurring payment configuration

Copy link List Plans

List all recurring payment plans

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The section to retrieve
intervalstring
Specify interval of the plan
Enumdailyweeklymonthlybiannuallyannually
amountinteger
The amount on the plans to retrieve
fromstring
The start date
tostring
The end date

Response

200Plan List response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/plan
curl https://api.paystack.co/plan \
  -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.plan.list({
  perPage: 100,
  page: 100
});
console.log(response.data);
require "paystack"

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

response = paystack.plan.list({
  per_page: 100,
  page: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Plans retrieved",
  "data": [
    {
      "subscriptions": [
        {
          "customer": 63,
          "plan": 27,
          "integration": 100032,
          "domain": "test",
          "start": 1458505748,
          "status": "complete",
          "quantity": 1,
          "amount": 100000,
          "subscription_code": "SUB_birvokwpp0sftun",
          "email_token": "9y62mxp4uh25das",
          "authorization": {
            "authorization_code": "AUTH_6tmt288t0o",
            "bin": "408408",
            "last4": "4081",
            "exp_month": "12",
            "exp_year": "2020",
            "channel": "card",
            "card_type": "visa visa",
            "bank": "TEST BANK",
            "country_code": "NG",
            "brand": "visa",
            "reusable": true,
            "signature": "SIG_uSYN4fv1adlAuoij8QXh",
            "account_name": "BoJack Horseman"
          },
          "easy_cron_id": null,
          "cron_expression": "0 0 * * 0",
          "next_payment_date": "2016-03-27T07:00:00.000Z",
          "open_invoice": null,
          "id": 8,
          "createdAt": "2016-03-20T20:29:08.000Z",
          "updatedAt": "2016-03-22T16:23:52.000Z"
        }
      ],
      "integration": 100032,
      "domain": "test",
      "name": "Satin Flower",
      "plan_code": "PLN_lkozbpsoyd4je9t",
      "description": null,
      "amount": 100000,
      "interval": "weekly",
      "send_invoices": true,
      "send_sms": true,
      "hosted_page": false,
      "hosted_page_url": null,
      "hosted_page_summary": null,
      "currency": "NGN",
      "id": 27,
      "createdAt": "2016-03-21T02:44:14.000Z",
      "updatedAt": "2016-03-21T02:44:14.000Z"
    },
    {
      "subscriptions": [],
      "integration": 100032,
      "domain": "test",
      "name": "Monthly retainer",
      "plan_code": "PLN_gx2wn530m0i3w3m",
      "description": null,
      "amount": 50000,
      "interval": "monthly",
      "send_invoices": true,
      "send_sms": true,
      "hosted_page": false,
      "hosted_page_url": null,
      "hosted_page_summary": null,
      "currency": "NGN",
      "id": 28,
      "createdAt": "2016-03-29T22:42:50.000Z",
      "updatedAt": "2016-03-29T22:42:50.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 Create Plan

Create a plan for recurring payments

Request Body

namerequiredstring
Name of plan
amountrequiredinteger
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
intervalrequiredstring
Payment interval
Enumdailyweeklymonthlybiannuallyannually
descriptionstring
A description for this plan
send_invoicesboolean
Set to false if you don't want invoices to be sent to your customers
send_smsboolean
Set to false if you don't want text messages to be sent to your customers
currencystring
Currency in which amount is set. Allowed values are NGN, GHS, ZAR or USD
invoice_limitinteger
Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.

Response

200Plan Create response
statusrequiredboolean
messagerequiredstring
datarequiredobject
16 object properties
currencyrequiredstring
namerequiredstring
amountrequiredinteger
intervalrequiredstring
integrationrequiredinteger
domainrequiredstring
plan_coderequiredstring
invoice_limitrequiredinteger
send_invoicesrequiredboolean
send_smsrequiredboolean
hosted_pagerequiredboolean
migraterequiredboolean
is_archivedrequiredboolean
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
POST/plan
curl https://api.paystack.co/plan \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic",
    "amount": 150000,
    "interval": "daily"
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

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

const response = await paystack.plan.create({
  name: "Basic",
  amount: 150000,
  interval: "daily"
});
console.log(response.data);
require "paystack"

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

response = paystack.plan.create({
  name: "Basic",
  amount: 150000,
  interval: "daily"
})
puts response.data
Response
{
  "status": true,
  "message": "Plan created",
  "data": {
    "name": "Monthly retainer",
    "amount": 500000,
    "interval": "monthly",
    "integration": 100032,
    "domain": "test",
    "plan_code": "PLN_gx2wn530m0i3w3m",
    "send_invoices": true,
    "send_sms": true,
    "hosted_page": false,
    "currency": "NGN",
    "id": 28,
    "createdAt": "2016-03-29T22:42:50.811Z",
    "updatedAt": "2016-03-29T22:42:50.811Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Plan

Get the details of a payment plan

Path Parameters

coderequiredstring
The plan code you want to fetch

Response

200Plan Fetch response
statusrequiredboolean
messagerequiredstring
datarequiredobject
28 object properties
subscriptionsrequiredarray[object]
pagesrequiredarray[object]
domainrequiredstring
namerequiredstring
plan_coderequiredstring
descriptionrequiredstring
amountrequiredinteger
intervalrequiredstring
invoice_limitrequiredinteger
send_invoicesrequiredboolean
send_smsrequiredboolean
hosted_pagerequiredboolean
hosted_page_urlrequiredstring
hosted_page_summaryrequiredstring
currencyrequiredstring
migraterequiredboolean
is_deletedrequiredboolean
is_archivedrequiredboolean
idrequiredinteger
integrationrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
pages_countrequiredinteger
subscribers_countrequiredinteger
subscriptions_countrequiredinteger
active_subscriptions_countrequiredinteger
total_revenuerequiredinteger
subscribersrequiredarray[object]
GET/plan/{code}
curl https://api.paystack.co/plan/PLN_gx2wn530m0i3w3m \
  -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.plan.fetch("PLN_gx2wn530m0i3w3m");
console.log(response.data);
require "paystack"

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

response = paystack.plan.fetch("PLN_gx2wn530m0i3w3m")
puts response.data
Response
{
  "status": true,
  "message": "Plan retrieved",
  "data": {
    "subscriptions": [],
    "integration": 100032,
    "domain": "test",
    "name": "Monthly retainer",
    "plan_code": "PLN_gx2wn530m0i3w3m",
    "description": null,
    "amount": 50000,
    "interval": "monthly",
    "send_invoices": true,
    "send_sms": true,
    "hosted_page": false,
    "hosted_page_url": null,
    "hosted_page_summary": null,
    "currency": "NGN",
    "id": 28,
    "createdAt": "2016-03-29T22:42:50.000Z",
    "updatedAt": "2016-03-29T22:42:50.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 Update Plan

Update a plan details on your integration

Path Parameters

coderequiredstring
The plan code you want to fetch

Request Body

namestring
Name of plan
amountinteger
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
intervalstring
Payment interval
Enumdailyweeklymonthlybiannuallyannually
descriptionboolean
A description for this plan
send_invoicesboolean
Set to false if you don't want invoices to be sent to your customers
send_smsboolean
Set to false if you don't want text messages to be sent to your customers
currencystring
Currency in which amount is set. Allowed values are NGN, GHS, ZAR or USD
invoice_limitinteger
Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.

Response

200Plan Update response
statusrequiredboolean
messagerequiredstring
PUT/plan/{code}
curl https://api.paystack.co/plan/PLN_gx2wn530m0i3w3m \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter",
    "amount": 100
  }' \
  -X PUT
import { Paystack } from "@paystack/paystack-sdk";

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

const response = await paystack.plan.update("PLN_gx2wn530m0i3w3m", {
  name: "Starter",
  amount: 100
});
console.log(response.data);
require "paystack"

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

response = paystack.plan.update("PLN_gx2wn530m0i3w3m", {
  name: "Starter",
  amount: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Plan updated. 1 subscription(s) affected"
}
{
  "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
}