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", 
5      "interval": "monthly", 
6      "amount": "500000"
7    }'
8-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": "customer@email.com", 
5      "amount": "500000", 
6      "plan": "PLN_xxxxxxxxxx" 
7    }'
8-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": {
14        "authorization_code": "AUTH_pmx3mgawyd",
15        "bin": "408408",
16        "last4": "4081",
17        "exp_month": "12",
18        "exp_year": "2020",
19        "channel": "card",
20        "card_type": "visa DEBIT",
21        "bank": "Test Bank",
22        "country_code": "NG",
23        "brand": "visa",
24        "reusable": true,
25        "signature": "SIG_2Gvc6pNuzJmj4TCchXfp",
26        "account_name": null
27      },
28      "invoice_limit": 0,
29      "subscription_code": "SUB_i6wmhzi0lu95oz7",
30      "email_token": "n27dvho4kjsf1sq",
31      "id": 161872,
32      "createdAt": "2020-05-22T12:56:12.514Z",
33      "updatedAt": "2020-05-22T12:56:12.514Z",
34      "cron_expression": "0 0 22 * *",
35      "next_payment_date": "2020-06-22T00:00:00.000Z"
36  }
37}

The response returned from the API includes a few parameters that are useful for managing your subscriptions, such as subscription_code, next_payment_date and email_token. next_payment_date indicates the next date that Paystack will try to charge the subscription, while email_token and subscription_code can be 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.

Subscription Statuses

Another useful parameter for managing your subscriptions is status. A subscription's status tells you what state a subscription is in, allowing you to take action if necessary. A subscription can either be:

StatusDescription
activeThe subscription is currently active, and will be charged on the next payment date.
completedThe subscription is complete, and will no longer be charged.
non-renewingThe subscription is still active but won't be charged on the next payment date and will be marked as completed.
attentionThe subscription is still active, but there was an issue while trying to charge the customer's card. The issue can be an expired card, insufficient funds, etc. We'll attempt charging the card again on the next payment date.
cancelledThe subscription has been cancelled.

Listen for subscription payments

Events are used to track subscriptions. When a subscription is created, a subscription.create 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": 895091250,
5    "domain": "test",
6    "status": "success",
7    "reference": "683e6787-7645-557a-a270-c9035c3a2b65",
8    "amount": 110000,
9    "message": null,
10    "gateway_response": "Approved",
11    "paid_at": "2020-11-23T11:00:09.000Z",
12    "created_at": "2020-11-23T11:00:03.000Z",
13    "channel": "card",
14    "currency": "NGN",
15    "ip_address": null,
16    "metadata": { "invoice_action": "create" },
17    "log": null,
18    "fees": 1650,
19    "fees_split": null,
20    "authorization": {
21      "authorization_code": "AUTH_v56svuyn23",
22      "bin": "408408",
23      "last4": "4081",
24      "exp_month": "12",
25      "exp_year": "2020",
26      "channel": "card",
27      "card_type": "visa ",
28      "bank": "TEST BANK",
29      "country_code": "NG",
30      "brand": "visa",
31      "reusable": true,
32      "signature": "SIG_H8F4hDXIARayPS41IUwG",
33      "account_name": null,
34      "receiver_bank_account_number": null,
35      "receiver_bank": null
36    },
37    "customer": {
38      "id": 31352593,
39      "first_name": "Test",
40      "last_name": "Two",
41      "email": "test2@live.com",
42      "customer_code": "CUS_mfkew13owtwcmb2",
43      "phone": "",
44      "metadata": null,
45      "risk_action": "default",
46      "international_format_phone": null
47    },
48    "plan": {
49      "id": 60905,
50      "name": "10% off first month",
51      "plan_code": "PLN_a5vr5skxg72f4lr",
52      "description": null,
53      "amount": 110000,
54      "interval": "monthly",
55      "send_invoices": true,
56      "send_sms": true,
57      "currency": "NGN"
58    },
59    "subaccount": {},
60    "split": {},
61    "order_id": null,
62    "paidAt": "2020-11-23T11:00:09.000Z",
63    "requested_amount": 110000
64  }
65