Plans

The Plans API allows you create and manage installment payment options on your integration.

Create Plan

Create a plan on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

content-typeString

Set value to application/json

Body Parameters

nameString

Name of plan

amountInteger

Amount should be in the subunit of the supported currency

intervalString

Interval in words. Valid intervals are: daily, weekly, monthly,quarterly, biannually (every 6 months), annually.

descriptionStringoptional

A description for this plan

send_invoicesBooleanoptional

Set to false if you don't want invoices to be sent to your customers

send_smsStringoptional

Set to false if you don't want text messages to be sent to your customers

currencyStringoptional

Currency in which amount is set

invoice_limitIntegeroptional

Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.

POST/plan
cURL
1#!/bin/sh
2url="https://api.paystack.co/plan"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "name": "Monthly retainer",
7 "interval": "monthly",
8 "amount": "500000"
9}'
10
11curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Plan created",
4 "data": {
5 "name": "Monthly retainer",
6 "amount": 500000,
7 "interval": "monthly",
8 "integration": 100032,
9 "domain": "test",
10 "plan_code": "PLN_gx2wn530m0i3w3m",
11 "send_invoices": true,
12 "send_sms": true,
13 "hosted_page": false,
14 "currency": "NGN",
15 "id": 28,
16 "createdAt": "2016-03-29T22:42:50.811Z",
17 "updatedAt": "2016-03-29T22:42:50.811Z"
18 }
19}

List Plans

List plans available on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

Query Parameters

perPageInteger

Specify how many records you want to retrieve per page. If not specify we use a default value of 50.

pageInteger

Specify exactly what page you want to retrieve. If not specify we use a default value of 1.

statusStringoptional

Filter list by plans with specified status

intervalStringoptional

Filter list by plans with specified interval

amountIntegeroptional

Filter list by plans with specified amount using the supported currency

GET/plan
cURL
1#!/bin/sh
2url="https://api.paystack.co/plan"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Plans retrieved",
4 "data": [
5 {
6 "subscriptions": [
7 {
8 "customer": 63,
9 "plan": 27,
10 "integration": 100032,
11 "domain": "test",
12 "start": 1458505748,
13 "status": "complete",
14 "quantity": 1,
15 "amount": 100000,
16 "subscription_code": "SUB_birvokwpp0sftun",
17 "email_token": "9y62mxp4uh25das",
18 "authorization": {
19 "authorization_code": "AUTH_6tmt288t0o",
20 "bin": "408408",
21 "last4": "4081",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa visa",
26 "bank": "TEST BANK",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_uSYN4fv1adlAuoij8QXh",
31 "account_name": "BoJack Horseman"
32 },
33 "easy_cron_id": null,
34 "cron_expression": "0 0 * * 0",
35 "next_payment_date": "2016-03-27T07:00:00.000Z",
36 "open_invoice": null,
37 "id": 8,
38 "createdAt": "2016-03-20T20:29:08.000Z",
39 "updatedAt": "2016-03-22T16:23:52.000Z"
40 }
41 ],
42 "integration": 100032,
43 "domain": "test",
44 "name": "Satin Flower",
45 "plan_code": "PLN_lkozbpsoyd4je9t",
46 "description": null,
47 "amount": 100000,
48 "interval": "weekly",
49 "send_invoices": true,
50 "send_sms": true,
51 "hosted_page": false,
52 "hosted_page_url": null,
53 "hosted_page_summary": null,
54 "currency": "NGN",
55 "id": 27,
56 "createdAt": "2016-03-21T02:44:14.000Z",
57 "updatedAt": "2016-03-21T02:44:14.000Z"
58 },
59 {
60 "subscriptions": [],
61 "integration": 100032,
62 "domain": "test",
63 "name": "Monthly retainer",
64 "plan_code": "PLN_gx2wn530m0i3w3m",
65 "description": null,
66 "amount": 50000,
67 "interval": "monthly",
68 "send_invoices": true,
69 "send_sms": true,
70 "hosted_page": false,
71 "hosted_page_url": null,
72 "hosted_page_summary": null,
73 "currency": "NGN",
74 "id": 28,
75 "createdAt": "2016-03-29T22:42:50.000Z",
76 "updatedAt": "2016-03-29T22:42:50.000Z"
77 }
78 ],
79 "meta": {
80 "total": 2,
81 "skipped": 0,
82 "perPage": 50,
83 "page": 1,
84 "pageCount": 1
85 }
86}

Fetch Plan

Get details of a plan on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

Path Parameters

id_or_codeString

The plan ID or code you want to fetch

GET/plan/:id_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/plan/:id_or_code"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Plan retrieved",
4 "data": {
5 "subscriptions": [],
6 "integration": 100032,
7 "domain": "test",
8 "name": "Monthly retainer",
9 "plan_code": "PLN_gx2wn530m0i3w3m",
10 "description": null,
11 "amount": 50000,
12 "interval": "monthly",
13 "send_invoices": true,
14 "send_sms": true,
15 "hosted_page": false,
16 "hosted_page_url": null,
17 "hosted_page_summary": null,
18 "currency": "NGN",
19 "id": 28,
20 "createdAt": "2016-03-29T22:42:50.000Z",
21 "updatedAt": "2016-03-29T22:42:50.000Z"
22 }
23}

Update Plan

Update a plan details on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

content-typeString

Set value to application/json

Path Parameters

id_or_codeString

Plan's ID or code

Body Parameters

nameString

Name of plan

amountInteger

Amount should be in the subunit of the supported currency

intervalString

Interval in words. Valid intervals are hourly, daily, weekly, monthly,quarterly, biannually (every 6 months), annually.

descriptionStringoptional

A description for this plan

send_invoicesBooleanoptional

Set to false if you don't want invoices to be sent to your customers

send_smsStringoptional

Set to false if you don't want text messages to be sent to your customers

currencyStringoptional

Currency in which amount is set

invoice_limitIntegeroptional

Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.

update_existing_subscriptionsBooleanoptional

Set to true if you want the existing subscriptions to use the new changes. Set to false and only new subscriptions will be changed. Defaults to true when not set.

PUT/plan/:id_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/plan/:id_or_code"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "name": "Monthly retainer (renamed)"
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Plan updated. 1 subscription(s) affected"
4}