Subscriptions
In a nutshell
Here is how to set up a subscription:
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.
1curl https://api.paystack.co/plan2-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:
- Adding Plan code to a transaction
- 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.
1curl https://api.paystack.co/transaction/initialize2-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
authorization
exists but is not passed as a parameter, Paystack picks the most recent authorization
to charge.1curl https://api.paystack.co/subscription2-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": null27 },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
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:
Status | Description |
---|---|
active | The subscription is currently active, and will be charged on the next payment date. |
completed | The subscription is complete, and will no longer be charged. |
non-renewing | The subscription is still active but won't be charged on the next payment date and will be marked as completed. |
attention | The 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. |
cancelled | The subscription has been cancelled. |
Listen for subscription payments
Events are used to track subscriptions. When a subscription is created, asubscription.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": null36 },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": null47 },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": 11000064 }65