Download the PHP package digikraaft/laravel-paystack-subscription without Composer
On this page you can find all versions of the php package digikraaft/laravel-paystack-subscription. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download digikraaft/laravel-paystack-subscription
More information about digikraaft/laravel-paystack-subscription
Files in digikraaft/laravel-paystack-subscription
Package laravel-paystack-subscription
Short Description A simple interface to Paystack's subscription billing services. It takes the pain of implementing subscription management off you.
License MIT
Homepage https://github.com/digikraaft/laravel-paystack-subscription
Informations about the package laravel-paystack-subscription
Paystack subscription in a Laravel application
Laravel Paystack Subscription offers a simple, fluent interface to Paystack's subscription billing services. No need to worry about writing subscription billing code anymore!
Installation
You can install the package via composer:
Configuration File
The Laravel Paystack Subscription package comes with a configuration file, here is the content of the file:
You can publish this config file with the following commands:
Database Migrations
You will need to publish the database migrations with these commands:
The migrations will add several columns to your users table as well as create a new subscriptions table to hold all of your customer's subscriptions.
Configuration
Billable Model
Before using the package, add the Billable trait to your model definition. This trait provides various methods to allow you to perform common billing tasks, such as creating subscriptions, renewing subscriptions and cancelling subscriptions:
The package assumes that your Billable model will be the default App\User class that ships with Laravel. If you wish to change this you can specify a different model in your .env file or in the published config file of the package:
Please note that if you're using a model other than Laravel's supplied App\User model, you'll need to publish and alter the migrations provided to match your alternative model's table name.
You can also specify a different table name for your billable model. See the Configuration File section.
API Keys
Next, you should configure your Paystack keys in your .env file. You can get your Paystack API keys from the Paystack dashboard.
Customers
Retrieving Customers
You can retrieve a customer by their Paystack ID using the PaystackSubscription::findBillable
method.
This will return an instance of the Billable model:
Creating Customers
If you need to create a Paystack customer without starting a subscription immediately,
you can do by using the createAsPaystackCustomer
method:
The code creates a customer in Paystack. You can then begin a subscription at a later date.
You can also use an optional $options
array to pass in any additional parameters that are supported by the Paystack API:
If the billable entity is already a customer in Paystack, you can retrieve the customer
object using the asPaystackCustomer
method:
If you are not sure that the billable entity is already a Paystack customer, the
createOrGetPaystackCustomer
method can be used to the get the customer object. This method
will create a new customer in Paystack if one does not already exist:
Updating Customers
If you need to update the Paystack customer with additional information, you can do this using
the updatePaystackCustomer
method:
Subscriptions
Creating Subscriptions
To create a subscription, first retrieve an instance of your billable model, which typically will be an instance of App\User. Once you have retrieved the model instance, you may use the newSubscription method to create the model's subscription:
The first argument passed to the newSubscription
method should be the name of the subscription.
If your application only offers a single subscription, you might call this default
or primary
.
The second argument is the specific plan the user is subscribing to.
This value should correspond to the plan's code in Paystack.
The create
method, which accepts a Paystack transaction ID,
will begin the subscription as well as update your database with the customer ID
and other relevant billing information.
You can check the implementation demo app to see how you can easily get this plan code and process payment to get
the $transactionID
from Paystack.
Authorization Code
When a customer is initially charged, Paystack creates an authorization code that can be used
later to bill the customer should the customer cancel.
If you would like to bill the customer at a later date, the authorization code can be passed as a second argument
to the create
method:
Additional Details
If you would like to specify additional customer information,
you may do so by passing them as the third argument to the create
method:
The additional fields specified must be supported by Paystack's API.
Checking Subscription Status
Once a user is subscribed to your application, you may easily check their
subscription status using a variety of convenient methods.
First, the subscribed
method returns true
if the user has an active subscription,
even if the subscription is cancelled and is due not to renew at the end of the billing period:
The subscribed
method can also be used in a route middleware,
allowing you to filter access to routes and controllers based on the user's subscription status:
An example of this can be seen in the demo implementation of this package here
The subscribedToPlan
method may be used to determine if the user is subscribed
to a given plan based on a given Paystack plan code.
In this example, we will determine if the user's default
subscription is actively subscribed to the PLN_paystackplan_code
plan:
By passing an array to the subscribedToPlan
method,
you may determine if the user's default
subscription
is actively subscribed to the PLN_paystackplan_code
or the PLN_paystackplan_code2
plan:
The active
method may be used to determine if the user currently has an active subscription:
The renews
method may be used to determine if the user's subscription will renew after the current billing period:
The daysLeft
method may be used to get the number of days left on the current billing period:
The endsAt
method may be used to get the date the current billing period will end:
Cancelled Subscription Status
To determine if the user has cancelled their subscription, you may use the isCancelled
method:
To determine if the user's subscription is past due, you may use the pastDue
method:
Subscription Scopes
The active
andcancelled
subscription states are also available as query scopes so that you may easily
query your database for subscriptions:
Cancelling Subscriptions
To cancel a subscription, call the cancel
method on the user's subscription:
When a subscription is cancelled, the paystack_status
column in your database is set to complete
.
This is based on Paytstack's implementation, meaning the subscription will not renew at the end of the billing period.
The subscription continues to be active until the end of the current billing period.
Resuming Subscriptions
If a user has cancelled their subscription and you wish to resume it, use the enable
method.
If the user cancels a subscription and then resumes that subscription before the subscription has fully expired, they will not be billed immediately. Instead, their subscription will be re-activated, and they will be billed on the original billing cycle.
Handling Paystack Webhooks
Paystack can notify your application about various events via webhooks. By default, a route that points to this package's webhook controller is configured through the service provider. This controller will handle all incoming webhook requests.
By default, this controller will automatically handle cancelling subscriptions, enabling subscriptions and failed invoices. This controller can be extended to handle any webhook event you like.
To ensure your application can handle Paystack webhooks, be sure to configure the webhook URL in the Paystack dashboard.
By default, this package's webhook controller listens to the /paystack/webhook
Webhooks & CSRF Protection
Since Paystack webhooks need to bypass Laravel's CSRF protection, be sure to list the URI as an exception in your
VerifyCsrfToken
middleware or list the route outside of the web
middleware group:
Defining Webhook Event Handlers
If you have additional webhook events you would like to handle,
extend the Webhook controller. Your method names should correspond to this package's
expected convention, specifically, methods should be prefixed with handle
and
the "camel case" name of the webhook you wish to handle.
For example, if you wish to handle the invoice.create
webhook,
you should add a handleInvoiceCreate
method to the controller:
Next, define a route to your controller within your routes/web.php
file.
This will overwrite the default shipped route:
Under the hood, wehbook handling is done using this package
You can find details about Paystack events here
Paystack API
If you would like to interact with the Paystack objects directly,
you may conveniently retrieve them using the asPaystack
method:
For details on how to interact with the object, check our paystack-php
package here
Testing
When testing an application that uses this package, you are free to mock the actual HTTP requests to the Paystack API; however, this requires you to partially re-implement this package's own behavior. We therefore recommend allowing your tests to hit the actual Paystack API. While this is slower, it provides more confidence that your application is working as expected and any slow tests may be placed within their own PHPUnit testing group.
When testing, remember that this package itself already has a great test suite, so you should only focus on testing the subscription and payment flow of your own application and not every underlying behavior of this package.
To get started, add the testing version of your Paystack secret and other required entities to your phpunit.xml
file:
When testing, ensure the environment variables above are created in paystack and correspond to the description in the values.
Use the command below to run your tests:
More Good Stuff
Check here for more awesome free stuff!
Alternatives
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
- Tim Oladoyinbo
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of laravel-paystack-subscription with dependencies
digikraaft/laravel-paystack-webhooks Version ^2.1
digikraaft/paystack-php Version ^2.2
laravel/framework Version ^9.0|^10.0