Laravel Cashier provides an expressive, fluent interface to subscriptions using Mollie's billing services.
This is an early release for this package. Things are likely to change before production-ready stability is reached.
At this point it's advised to only use this package with Mollie's test API.
The more we learn, the faster we will get to a stable release. Help us get there faster by opening a ticket in the issue tracker with your comments, suggestions, questions, problems etc..
You can pull this package in using composer:
composer require laravel/cashier-mollie "^0.1"
Once you have pulled in the package:
-
Run
php artisan cashier:install
. -
Add these fields to your billable model's migration (typically the default "create_user_table" migration):
$table->string('mollie_customer_id')->nullable(); $table->string('mollie_mandate_id')->nullable(); $table->decimal('tax_percentage', 6, 4)->default(0); // optional $table->dateTime('trial_ends_at')->nullable(); // optional $table->text('extra_billing_information')->nullable(); // optional
-
Run the migrations:
php artisan migrate
-
Set the
MOLLIE_KEY
in your .env file. You can obtain an API key from the Mollie.com dashboard:MOLLIE_KEY="test_xxxxxxxxxxx"
-
Prepare the configuration files:
-
configure at least one subscription plan in
config/cashier_plans.php
. -
in
config/cashier_coupons.php
you can manage any coupons. By default an example coupon is enabled. Consider disabling it before deploying to production. -
the base configuration is in
config/cashier
. Be careful while modifying this, in most cases you will not need to.
-
-
Prepare the billable model (typically the default Laravel User model):
-
Add the
Laravel\Cashier\Billable
trait. -
Optionally, override the method
mollieCustomerFields()
to configure what billable model fields are stored while creating the Mollie Customer. Out of the box themollieCustomerFields()
method uses the default Laravel User model fields:
public function mollieCustomerFields() { return [ 'email' => $this->email, 'name' => $this->name, ]; }
Learn more about storing data on the Mollie Customer here.
- Implement
Cashier\Contracts\ProvidesInvoiceInformation
interface. For example:
/** * Get the receiver information for the invoice. * Typically includes the name and some sort of (E-mail/physical) address. * * @return array An array of strings */ public function getInvoiceInformation() { return [$this->name, $this->email]; } /** * Get additional information to be displayed on the invoice. Typically a note provided by the customer. * * @return string|null */ public function getExtraBillingInformation() { return null; }
-
-
Schedule a periodic job to execute
Cashier::run()
.$schedule->command('cashier:run') ->daily() // run as often as you like (Daily, monthly, every minute, ...) ->withoutOverlapping(); // make sure to include this
You can find more about scheduling jobs using Laravel here.
🎉 You're now good to go :).
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:
$user = User::find(1);
// Make sure to configure the 'premium' plan in config/cashier.php
$result = $user->newSubscription('main', 'premium')->create();
If the customer already has a valid Mollie mandate, the $result
will be a Subscription
.
If the customer has no valid Mollie mandate yet, the $result
will be a RedirectResponse
, redirecting the customer to
the Mollie checkout to make the first payment. Once the payment has been received the subscription will start.
Here's a basic controller example for creating the subscription:
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;
class CreateSubscriptionController extends Controller
{
/**
* @param string $plan
* @return \Illuminate\Http\RedirectResponse
*/
public function __invoke(string $plan)
{
$user = Auth::user();
$name = ucfirst($plan) . ' membership';
if(!$user->subscribed($name, $plan)) {
$result = $user->newSubscription($name, $plan)->create();
if(is_a($result, RedirectResponse::class)) {
return $result; // Redirect to Mollie checkout
}
return back()->with('status', 'Welcome to the ' . $plan . ' plan');
}
return back()->with('status', 'You are already on the ' . $plan . ' plan');
}
}
In order to always enforce a redirect to the Mollie checkout page, use the newSubscriptionViaMollieCheckout
method
instead of newSubscription
:
$redirect = $user->newSubscriptionViaMollieCheckout('main', 'premium')->create(); // make sure to configure the 'premium' plan in config/cashier.php
Coupon handling in Cashier Mollie is designed with full flexibility in mind.
Coupons can be defined in config/cashier_coupons.php
.
You can provide your own coupon handler by extending
\Cashier\Discount\BaseCouponHandler
.
Out of the box, a basic FixedDiscountHandler
is provided.
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 currently within its trial period:
if ($user->subscribed('main')) {
//
}
The subscribed
method also makes a great candidate for a route middleware, allowing you to filter access to routes and controllers based on the user's subscription status:
public function handle($request, Closure $next)
{
if ($request->user() && ! $request->user()->subscribed('main')) {
// This user is not a paying customer...
return redirect('billing');
}
return $next($request);
}
If you would like to determine if a user is still within their trial period, you may use the onTrial
method. This method can be useful for displaying a warning to the user that they are still on their trial period:
if ($user->subscription('main')->onTrial()) {
//
}
The subscribedToPlan
method may be used to determine if the user is subscribed to a given plan based on a configured plan. In this example, we will determine if the user's main
subscription is actively subscribed to the monthly
plan:
if ($user->subscribedToPlan('monthly', 'main')) {
//
}
To determine if the user was once an active subscriber, but has cancelled their subscription, you may use the cancelled
method:
if ($user->subscription('main')->cancelled()) {
//
}
You may also determine if a user has cancelled their subscription, but are still on their "grace period" until the subscription fully expires. For example, if a user cancels a subscription on March 5th that was originally scheduled to expire on March 10th, the user is on their "grace period" until March 10th. Note that the subscribed
method still returns true
during this time:
if ($user->subscription('main')->onGracePeriod()) {
//
}
After a user is subscribed to your application, they may occasionally want to change to a new subscription plan. To swap a user to a new subscription, pass the plan's identifier to the swap
or swapNextCycle
method:
$user = App\User::find(1);
// Swap right now
$user->subscription('main')->swap('other-plan-id');
// Swap once the current cycle has completed
$user->subscription('main')->swapNextCycle('other-plan-id');
If the user is on trial, the trial period will be maintained. Also, if a "quantity" exists for the subscription, that quantity will also be maintained.
Sometimes subscriptions are affected by "quantity". For example, your application might charge €10 per month per user on an account. To easily increment or decrement your subscription quantity, use the incrementQuantity
and decrementQuantity
methods:
$user = User::find(1);
$user->subscription('main')->incrementQuantity();
// Add five to the subscription's current quantity...
$user->subscription('main')->incrementQuantity(5);
$user->subscription('main')->decrementQuantity();
// Subtract five to the subscription's current quantity...
$user->subscription('main')->decrementQuantity(5);
Alternatively, you may set a specific quantity using the updateQuantity
method:
$user->subscription('main')->updateQuantity(10);
To specify the tax percentage a user pays on a subscription, implement the taxPercentage
method on your billable model, and return a numeric value between 0 and 100, with no more than 2 decimal places.
public function taxPercentage() {
return 20;
}
The taxPercentage
method enables you to apply a tax rate on a model-by-model basis, which may be helpful for a user base that spans multiple countries and tax rates.
When changing the hard-coded value returned by the taxPercentage
method, the tax settings on any existing subscriptions for the user will remain the same. If you wish to update the tax value for existing subscriptions with the returned taxPercentage
value, you should call the syncTaxPercentage
method on the user's subscription instance:
$user->subscription('main')->syncTaxPercentage();
Not (yet) implemented, but you could make this work by scheduling Cashier::run()
to only execute on a specific day of the month.
To cancel a subscription, call the cancel
method on the user's subscription:
$user->subscription('main')->cancel();
When a subscription is cancelled, Cashier will automatically set the ends_at
column in your database. This column is used to know when the subscribed
method should begin returning false
. For example, if a customer cancels a subscription on March 1st, but the subscription was not scheduled to end until March 5th, the subscribed
method will continue to return true
until March 5th.
You may determine if a user has cancelled their subscription but are still on their "grace period" using the onGracePeriod
method:
if ($user->subscription('main')->onGracePeriod()) {
//
}
If a user has cancelled their subscription and you wish to resume it, use the resume
method. The user must still be on their grace period in order to resume a subscription:
$user->subscription('main')->resume();
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.
Coming soon.
If you would like to offer trial periods to your customers while still collecting payment method information up front, you should use the trialDays
method when creating your subscriptions:
$user = User::find(1);
$user->newSubscription('main', 'monthly')
->trialDays(10)
->create();
This method will set the trial period ending date on the subscription record within the database.
{note} The customer will be redirected to the Mollie checkout page to make the first payment in order to register a mandate. You can modify the amount in the cashier config file.
{note} If the customer's subscription is not cancelled before the trial ending date they will be charged as soon as the trial expires, so you should be sure to notify your users of their trial ending date.
The trialUntil
method allows you to provide a Carbon
instance to specify when the trial period should end:
use Carbon\Carbon;
$user->newSubscription('main', 'monthly')
->trialUntil(Carbon::now()->addDays(10))
->create();
You may determine if the user is within their trial period using either the onTrial
method of the user instance, or the onTrial
method of the subscription instance. The two examples below are identical:
if ($user->onTrial('main')) {
//
}
if ($user->subscription('main')->onTrial()) {
//
}
If you would like to offer trial periods without collecting the user's payment method information up front, you may set the trial_ends_at
column on the user record to your desired trial ending date. This is typically done during user registration:
$user = User::create([
// Populate other user properties...
'trial_ends_at' => now()->addDays(10),
]);
{note} Be sure to add a date mutator for
trial_ends_at
to your model definition.
Cashier refers to this type of trial as a "generic trial", since it is not attached to any existing subscription. The onTrial
method on the User
instance will return true
if the current date is not past the value of trial_ends_at
:
if ($user->onTrial()) {
// User is within their trial period...
}
You may also use the onGenericTrial
method if you wish to know specifically that the user is within their "generic" trial period and has not created an actual subscription yet:
if ($user->onGenericTrial()) {
// User is within their "generic" trial period...
}
Once you are ready to create an actual subscription for the user, you may use the newSubscription
method as usual:
$user = User::find(1);
$user->newSubscription('main', 'monthly')->create();
Cashier automatically handles subscription cancellation on failed charges.
Additionally, listen for the following events (in the Laravel\Cashier\Events
namespace) to add app specific behaviour:
OrderPaymentPaid
andOrderPaymentFailed
MandatePaymentPaid
andMandatePaymentFailed
Coming soon.
Listen for the OrderProcessed
event (in the Laravel\Cashier\Events
namespace).
When a new order has been processed, you can grab the invoice by
$invoice = $event->order->invoice();
$invoice->view(); // get a Blade view
$invoice->pdf(); // get a pdf of the Blade view
$invoice->download(); // get a download response for the pdf
To list invoices, access the user's orders using: $user->orders->invoices()
.
This includes invoices for all orders, even unprocessed or failed orders.
Coming soon.
In some cases (i.e. when swapping to a cheaper plan), a customer can have overpaid. The amount that has been overpaid will be added to the customer balance.
The customer balance is automatically processed in each Order.
A separate balance is kept for each currency.
There are a few methods available to interact with the balance directly. Use these with care:
$credit = $user->credit('EUR');
$user->addCredit(new Amount(10, 'EUR'); // add €10.00
$user->hasCredit('EUR');
When an Order with a negative total amount due is processed, that amount is credited to the user balance.
A BalanceTurnedStale
event will be raised if the user has no active subscriptions at that moment.
Listen for this event if you'd like to refund the remaining balance and/or want to notify the user.
Mollie provides a checkout tailored to the customer's locale. For this it guesses the visitor's locale. To override the
default locale, configure it in config/cashier.php
. This is convenient for servicing a single country.
If you're dealing with multiple locales and want to override Mollie's default behaviour, implement the getLocale()
method on the billable model. A common way is to add a nullable locale
field to the user table and retrieve its value:
class User extends Model
{
/**
* @return string
* @link https://docs.mollie.com/reference/v2/payments-api/create-payment#parameters
* @example 'nl_NL'
*/
public function getLocale() {
return $this->locale;
}
}
You can listen for the following events from the Laravel\Cashier\Events namespace:
The user has a positive account balance, but no active subscriptions. Consider a refund.
A coupon was applied to an OrderItem. Note the distinction between redeeming a coupon and applying a coupon. A redeemed coupon can be applied to multiple orders. I.e. applying a 6 month discount on a monthly subscription using a single (redeemed) coupon.
The first payment (used for obtaining a mandate) has failed.
The first payment (used for obtaining a mandate) was successful.
The mollie_mandate_id
was cleared on the billable model. This happens when a payment has failed because of a invalid
mandate.
An Order was created.
The payment for an order has failed.
The payment for an order was successful.
The order has been fully processed.
The subscription was cancelled.
The subscription plan was swapped.
The subscription quantity was updated.
Some business cases will require dynamic subscription amounts.
To allow for full flexibility Cashier Mollie allows you to define your own set of Subscription OrderItem preprocessors. These preprocessors are invoked when the OrderItem is due, right before being processed into a Mollie payment.
If you're using metered billing, this is a convenient place to calculate the amount based on the usage statistics and reset any counters for the next billing cycle.
You can define the preprocessors in the cashier_plans
config file.
This Cashier implementation schedules triggering payments from the client side, instead of relying on subscription management at Mollie. (Yes, Mollie also offers a Subscription API, but it does not support all of Cashier features, so this package provides its own subscription engine.)
From a high level perspective, this is what the process looks like:
- A
Subscription
is created using theMandatePaymentSubscriptionBuilder
(redirecting to Mollie's checkout to create aMandate
) orPremandatedSubscriptionBuilder
(using an existingMandate
). - The
Subscription
yields a scheduledOrderItem
at the beginning of each billing cycle. OrderItems
which are due are preprocessed and bundled intoOrders
whenever possible by a scheduled job (i.e. daily). This is done so your customer will receive a single payment/invoice for multiple items later on in the chain). Preprocessing theOrderItems
may involve applying dynamic discounts or metered billing, depending on your configuration.- The
Order
is processed by the same scheduled job into a payment:- First, (if available) the customer's balance is processed in the
Order
. - If the total due is positive, a Mollie payment is incurred.
- If the total due is 0, nothing happens.
- If the total due is negative, the amount is added to the user's balance. If the user has no active subscriptions left, the
BalanceTurnedStale
event will be raised.
- First, (if available) the customer's balance is processed in the
- You can generate an
Invoice
(html/pdf) for the user.
By default Cashier Mollie uses unsignedInteger
fields for the billable model relationships.
If required for your billable model, modify the cashier migrations for UUIDs:
// Replace this:
$table->unsignedInteger('owner_id');
// By this:
$table->uuid('owner_id');
Cashier Mollie is tested against Mollie's test API.
Start with copying phpunit.xml.dist
into phpunit.xml
, and set these environment variables in phpunit.xml
:
Mollie API test key You can obtain this key from the dashboard right after signing up.
<env name="MOLLIE_KEY" value="YOUR_VALUE_HERE"/>
ID of a customer with a valid directdebit mandate
<env name="MANDATED_CUSTOMER_DIRECTDEBIT" value="YOUR_VALUE_HERE"/>
Mandate's ID (of the previously mentioned customer)
<env name="MANDATED_CUSTOMER_DIRECTDEBIT_MANDATE_ID" value="YOUR_VALUE_HERE"/>
ID of a successful ("paid) payment by the customer Use a 1000 EUR amount.
<env name="PAYMENT_PAID_ID" value="YOUR_VALUE_HERE"/>
ID of an unsuccessful ("failed") payment by the customer
<env name="PAYMENT_FAILED_ID" value="YOUR_VALUE_HERE"/>
Now you can run:
composer test
Please see CONTRIBUTING for details.
If you discover any security related issues, please email support@mollie.com instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.