Subscriptions

In A Nutshell
In a nutshell
Subscriptions allow customers to pay a specific amount for a recurring interval you set . With subscriptions, you only need to initialize the first payment, and Paystack will handle the renewals when they are due.

Here is how to set up a subscription:

  1. Create a Plan
  2. Create a subscription
  3. Listen for subscription payments

Create a plan

A plan is a framework for a subscription. This is where you decide the amount, interval and currency in which the subscription will be paid. Every subscription needs to be on a plan. You can create a Plan via the Paystack Dashboard or using the create planAPI endpoint.

Show Response
1curl https://api.paystack.co/plan
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ name: "Monthly Retainer", interval: "monthly", amount: "500000"}'
5-X POST
1{
2 "status": true,
3 "message": "Plan created",
4 "data": {
5 "name": "Monthly Retainer",
6 "interval": "monthly",
7 "amount": 500000,
8 "integration": 428626,
9 "domain": "test",
10 "currency": "NGN",
11 "plan_code": "PLN_u4cqud8vabi89hx",
12 "invoice_limit": 0,
13 "send_invoices": true,
14 "send_sms": true,
15 "hosted_page": false,
16 "migrate": false,
17 "id": 49122,
18 "createdAt": "2020-05-22T12:36:12.333Z",
19 "updatedAt": "2020-05-22T12:36:12.333Z"
20 }
21}

When a plan is created, the response contains a plan code that is used to create a subscription.

The plan intervals we have are dailyweeklymonthlyquarterly and annually. You can also set invoice limits to determine how many times a user can be charged for this plan. If you set invoice_limit: 5 to the request above, the user will be charged only 5 times.

Create a subscription

There are 2 ways to create a subscription:

  1. Adding Plan code to a transaction
  2. Using the create subscriptionAPI endpoint

Adding Plan code to a transaction

You can include the plan code in the initialize transactionAPI object when the user is about to make the first payment.

Show Response
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ email: "[email protected]", amount: "500000",
5 plan: "PLN_xxxxxxxxxx" }'
6-X POST
1{
2 "status": true,
3 "message": "Authorization URL created",
4 "data": {
5 "authorization_url": "https://checkout.paystack.com/nkdks46nymizns7",
6 "access_code": "nkdks46nymizns7",
7 "reference": "nms6uvr1pl"
8 }
9}

Using the Create Subscription endpoint

To use this, you would need both the customer code and authorization.

Note
If an authorization exists but is not passed as a parameter, Paystack picks the most recent authorization to charge.
Show Response
1curl https://api.paystack.co/subscription
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ customer: "CUS_xxxxxxxxxx", plan: "PLN_xxxxxxxxxx" }'
5-X POST
1{
2 "status": true,
3 "message": "Subscription successfully created",
4 "data": {
5 "customer": 24259516,
6 "plan": 49122,
7 "integration": 428626,
8 "domain": "test",
9 "start": 1590152172,
10 "status": "active",
11 "quantity": 1,
12 "amount": 500000,
13 "authorization": 92011604,
14 "invoice_limit": 0,
15 "subscription_code": "SUB_i6wmhzi0lu95oz7",
16 "email_token": "n27dvho4kjsf1sq",
17 "id": 161872,
18 "createdAt": "2020-05-22T12:56:12.514Z",
19 "updatedAt": "2020-05-22T12:56:12.514Z",
20 "cron_expression": "0 0 22 * *",
21 "next_payment_date": "2020-06-22T00:00:00.000Z"
22 }
23}

The response returned include subscription_codenext_payment_date and email_token. The email token and subscription are used to cancel the subscriptionAPI.

Subscriptions are not retried
If a subscription charge fails, we do not retry it. Subscriptions are ideal for situations where value is delivered after payment. e.g. Payment for internet service or a streaming service.

Listen for subscription payments

Events are used to track subscriptions. When a subscription is created, a create.subscription event is sent to your webhook URL. To track subscription payments, watch for the charge.success event sent for successful subscriptions.
1{
2 "event":"charge.success",
3 "data":{
4 "id":302961,
5 "domain":"live",
6 "status":"success",
7 "reference":"qTPrJoy9Bx",
8 "amount":10000,
9 "message":null,
10 "gateway_response":"Approved by Financial Institution",
11 "paid_at":"2016-09-30T21:10:19.000Z",
12 "created_at":"2016-09-30T21:09:56.000Z",
13 "channel":"card",
14 "currency":"NGN",
15 "ip_address":"41.242.49.37",
16 "metadata":0,
17 "fees":null,
18 "customer": {
19 "id": 902735,
20 "first_name": null,
21 "last_name": null,
22 "email": "[email protected]",
23 "customer_code": "CUS_1psu1flkeh1dzm8",
24 "phone": null,
25 "metadata": null,
26 "risk_action": "default"
27 },
28 "plan": "PLN_tq8ur7pqz80fbpi",
29 "paidAt": "2018-06-10T18:00:25.000Z",
30 "createdAt": "2018-06-10T17:59:59.000Z",
31 "transaction_date": "2018-06-10T17:59:59.000Z",
32 "plan_object": {
33 "id": 6743,
34 "name": "Test Plans",
35 "plan_code": "PLN_tq8ur7pqz80fbpi",
36 "description": "This is to test listing plans, etc etc",
37 "amount": 200000,
38 "interval": "hourly",
39 "send_invoices": true,
40 "send_sms": true,
41 "currency": "NGN"
42 },
43 "subaccount": {}
44 }
45}
46