Payments
Set up your first subscription in 15 minutes
In a nutshell
Create a plan, subscribe a customer, and handle recurring billing events with a minimal Paystack integration.
This tutorial walks through a minimal Paystack subscription flow. You will create a plan, subscribe a customer, and add a webhook handler for the billing events that keep your app in sync.
Copy linkBefore you begin
You need:
- a Paystack account in test mode
YOUR_SECRET_KEYYOUR_PUBLIC_KEY- a server that can make requests to
https://api.paystack.co - a public webhook URL
Copy linkStep 1: Create a plan
Create the recurring pricing model first.
curl https://api.paystack.co/plan \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Starter Plan",
"interval": "monthly",
"amount": 500000
}'
Save the returned plan_code.
Copy linkStep 2: Subscribe the customer during a payment
Initialize a transaction and include the plan code. Paystack will charge the customer and create the subscription after the payment succeeds.
curl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 500000,
"plan": "PLN_xxxxxxxxxx"
}'
Redirect the customer to the authorization URL returned by Paystack, or complete the same initialization through your Paystack frontend flow.
Copy linkStep 3: Create a subscription from an existing authorization
If the customer has already paid on your integration before, you can create a subscription directly instead.
curl https://api.paystack.co/subscription \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_xxxxxxxxxx",
"plan": "PLN_xxxxxxxxxx"
}'
If the customer has multiple reusable authorizations, pass the one you want with the authorization field.
Copy linkStep 4: Add a webhook endpoint
Add your webhook URL in the Paystack Dashboard and verify the signature in your server.
const crypto = require('crypto')
function verifyPaystack(req) {
const signature = crypto
.createHmac('sha512', 'YOUR_SECRET_KEY')
.update(JSON.stringify(req.body))
.digest('hex')
return signature === req.headers['x-paystack-signature']
}
Copy linkStep 5: Handle subscription events
Use the event name to drive billing state in your app.
app.post('/paystack/webhook', (req, res) => {
if (!verifyPaystack(req)) return res.sendStatus(401)
const { event, data } = req.body
res.sendStatus(200)
if (event === 'subscription.create') {
// store subscription code and mark customer as subscribed
}
if (event === 'invoice.create') {
// mark the next billing cycle as pending
}
if (event === 'charge.success') {
// grant or extend access for the billing period
}
if (event === 'invoice.payment_failed') {
// notify the customer and flag the account for attention
}
if (event === 'subscription.not_renew' || event === 'subscription.disable') {
// update renewal or cancellation status
}
})
Copy linkStep 6: Test the cycle in test mode
Run the initial payment with Paystack test details, confirm that subscription.create is received, and inspect invoice-related events as the subscription progresses.
Copy linkWhat you built
You created a Paystack billing flow with a reusable plan, a customer subscription, and webhook handling for creation, invoice generation, successful recurring charges, failed invoices, and subscription cancellation states.