docs
Cancel

No result found for:

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 daily, weekly, monthly, quarterly 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_code, next_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. Payement 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.
  • JSON
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