Subscriptions

The SubscriptionResource allows you to create and manage recurring payments on your integration.

Create Subscription

Create a subscription on your integration.

Prerequisite: Before you can create a subscription for a user, you must have already created a Plan.

$subscription = paystack()->subscription()->create([
    'customer' => '[email protected]', // or customer code
    'plan' => 'PLN_gx2wn530m0i3w3m',
    'start_date' => '2023-05-16T00:30:13+01:00' // Optional
]);

Parameters

Parameter	Type	Required	Description
customer	String	Yes	Customer's email address or customer code.
plan	String	Yes	Plan code.
authorization	String	No	If customer has multiple authorizations, you can set the desired authorization you wish to use for this subscription here. If this is not supplied, the customer's most recent authorization would be used.
start_date	String	No	Set the date for the first debit. (ISO 8601 format).

List Subscriptions

List subscriptions available on your integration.

// List all subscriptions
$subscriptions = paystack()->subscription()->list();

// Filter subscriptions
$filtered = paystack()->subscription()->list([
    'perPage' => 20,
    'customer' => 12345, // Customer ID
    'plan' => 67890 // Plan ID
]);

Fetch Subscription

Get details of a subscription on your integration.

$idOrCode = 'SUB_vsyqdmlzble3uii';

$details = paystack()->subscription()->fetch($idOrCode);

Enable Subscription

Enable a subscription on your integration.

$code = 'SUB_vsyqdmlzble3uii';
$token = 'd7gofp6yppn3qz7'; // Email token

$response = paystack()->subscription()->enable([
    'code' => $code,
    'token' => $token
]);

Disable Subscription

Disable (cancel) a subscription on your integration.

$code = 'SUB_vsyqdmlzble3uii';
$token = 'd7gofp6yppn3qz7'; // Email token

$response = paystack()->subscription()->disable($code, $token);

Manage Subscription

Generate Update Link

Generate a link for the customer to update their card or manage their subscription.

$code = 'SUB_vsyqdmlzble3uii';

$link = paystack()->subscription()->getUpdateLink($code);

// Redirect user to the link
return redirect($link);

Send Update Link via Email

Email a customer a link for updating the card on their subscription.

$code = 'SUB_vsyqdmlzble3uii';

$response = paystack()->subscription()->sendUpdateLink($code);

Subscription Management Guide

Creating a Subscription

There are two main ways to create a subscription:

1. Adding Plan Code to a Transaction: When initializing a transaction, include the plan parameter with the plan code. This will charge the customer the plan amount and automatically subscribe them upon successful payment.
2. Using the Create Subscription Endpoint: Use the create method as shown above. This requires the customer to have an existing authorization (i.e., they must have made a previous payment).

Subscription Statuses

Status	Description
active	The subscription is currently active and will be charged on the next payment date.
non-renewing	The subscription is active but won't be charged on the next payment date (e.g., cancelled but period not yet over).
attention	There was an issue charging the customer's card (e.g., insufficient funds). Paystack will retry.
completed	The subscription is complete and will no longer be charged.
cancelled	The subscription has been cancelled.

Handling Payment Issues

If a subscription status is attention, check the most_recent_invoice object in the subscription details to see the failure reason. You can use the "Generate Update Link" feature to allow the customer to update their payment method.