Sign in

Payments

Set up your first subscription in 15 minutes

View as Markdown

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_KEY
  • YOUR_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.

Was this page helpful?