repository·main·Indexed 41 days ago
https://github.com/mollie/laravel-cashier-mollieAn official integration providing an expressive, fluent interface for managing subscription billing cycles, payments, and customer relationships in Laravel applications using Mollie's billing services. Supports subscription plans, coupons, trial periods (including generic trials and mandate-upfront trials), and one-time charges.
Mollie maintains a customer balance for each currency. This balance is automatically applied to Orders (for example, when a customer has overpaid due to a plan swap).
If an Order is processed with a negative total amount due, that amount is automatically credited to the user's balance. If the user has no active subscriptions at that moment, a BalanceTurnedStale event is raised. You should listen for this event to handle refunds or user notifications.
Warning: Use the direct balance manipulation methods with caution.
// Check credit for a specific currency
$credit = $user->credit('EUR');
// Manually add credit
$user->addCredit(money(1000, 'EUR')); // adds €10.00
// Check if user has credit
$user->hasCredit('EUR');When a payment related to a subscription fails, Cashier automatically cancels the subscription immediately.
If the payment is successfully retried (e.g., via retryNow()), the subscription will be reactivated and will continue its previous billing cycle as if the failure had not occurred.
You can access all invoices associated with a user by accessing their orders via $user->orders->invoices(). This collection includes invoices for all orders, including those that are unprocessed or failed.
// Accessing all invoices through the orders relationship
$invoices = $user->orders->invoices();Unlike standard Mollie subscriptions, Cashier Mollie uses its own subscription engine to schedule payments from the client side. This allows for features not supported by Mollie's native Subscription API.
The Subscription Lifecycle:
Subscription is created using either MandatePaymentSubscriptionBuilder (redirects to Mollie checkout to create a Mandate) or PremandatedSubscriptionBuilder (uses an existing Mandate).Subscription generates a scheduled OrderItem at the start of every billing cycle.OrderItems (applying dynamic discounts or metered billing) and bundles them into Orders so customers receive a single invoice for multiple items.Order:BalanceTurnedStale event is raised.Invoice documents for the user.Cashier Mollie applies prorating by default when a subscription quantity is updated or a plan is switched.
Prorating Process:
Order is generated, applying the credited balance to the new total.Note: This does not apply to $subscription->swapNextCycle('other-plan'). That method waits until the end of the current billing cycle to update the plan, which is useful for downgrades.
Cashier Mollie automatically handles default Mollie webhook logic, such as cancelling a subscription if a recurring charge fails.
To implement application-specific behavior (e.g., granting access to a user or notifying an admin), you should listen for specific events provided by the package in the Laravel\ ext{Cashier}\\text{Events} namespace.
Available events for custom logic:
OrderPaymentPaid: Triggered when an order payment succeeds.OrderPaymentFailed: Triggered when an order payment fails.FirstPaymentPaid: Triggered when the initial payment for a subscription succeeds.FirstPaymentFailed: Triggered when the initial payment for a subscription fails.To make a model (typically the User model) billable, you must perform the following steps:
Laravel\ Cashier\\Billable trait to the model.mollieCustomerFields() to define which model fields should be sent to Mollie when creating a Customer.Laravel\\Cashier\\Order\\Contracts\\ProvidesInvoiceInformation interface to provide data for invoices.Example implementation:
use Laravel\Cashier\Billable;
class User extends Authenticatable
{
use Billable;
public function mollieCustomerFields()
{
return [
'email' => $this->email,
'name' => $this->name,
];
}
/**
* Get the receiver information for the invoice.
* @return array An array of strings
*/
public function getInvoiceInformation()
{
return [$this->name, $this->email];
}
/**
* Get additional information to be displayed on the invoice.
* @return string|null
*/
public function getExtraBillingInformation()
{
return null;
}
}public function mollieCustomerFields() {
return [
'email' => $this->email,
'name' => $this->name,
];
}
public function getInvoiceInformation()
{
return [$this->name, $this->email];
}
public function getExtraBillingInformation()
{
return null;
}Cashier uses English translation strings by default (e.g., for cycle definitions when order items are created). You can translate these using Laravel's standard localization feature by following these steps:
resources/lang/vendor/cashier/ named after your desired locale (e.g., resources/lang/vendor/cashier/fr).When your application's locale is set to the language you created, Cashier will automatically use your custom translations instead of the defaults.
php artisan vendor:publish --tag=cashier-translationsWhen Mollie successfully processes a refund, Cashier dispatches the RefundProcessed event. You can use this event to access the automatically generated credit order and its corresponding invoice receipt.
Once you have the invoice object, you can:
$invoice->view(): Retrieve a Blade view.$invoice->pdf(): Retrieve a PDF of the Blade view.$invoice->download(): Return a download response for the PDF.Credit orders and invoices are treated as regular Cashier orders and invoices, meaning they will appear in the user's standard order and invoice lists (e.g., $user->orders or $user->orders->invoices()).
$creditOrder = $refundProcessedEvent->refund->order;
$invoice = $creditOrder->invoice();
$invoice->view(); // get a Blade view
$invoice->pdf(); // get a pdf of the Blade view
$invoice->download(); // get a download response for the pdfFor business cases requiring dynamic subscription amounts, Cashier Mollie provides a mechanism to define custom Subscription OrderItem preprocessors.
These preprocessors are invoked immediately before an OrderItem is processed into a Mollie payment. This allows you to calculate the final billing amount dynamically based on real-time usage statistics. You can also use this hook to reset usage counters for the next billing cycle.
To implement this, you must define your custom preprocessor classes in the cashier_plans configuration file.
// In your cashier_plans config file, define your preprocessors:
'preprocessors' => [
App\Billing\MyMeteredUsagePreprocessor::class,
],A "generic trial" allows you to offer a trial period without collecting payment information immediately. This is achieved by setting a trial_ends_at value on the user record, typically during registration.
Note: You must add a date mutator for the trial_ends_at column in your Eloquent model definition to ensure it is handled correctly as a date object.
$user = User::create([
// Populate other user properties...
'trial_ends_at' => now()->addDays(10),
]);