Subscriptions
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:
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", 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:
- 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"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.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 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. Payment for internet service or a streaming service.
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",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