Cashier 10.0 is a major release that provides support for new Stripe APIs as well as provide compliance with SCA regulations in Europe that begin September 2019. If you have a business in the EU, we recommend you review Stripe's guide on PSD2 and SCA as well as their documentation on the SCA API's.
In this upgrade guide we'll try to cover as much as possible. Please read it thoroughly and also review the corresponding pull requests. Note that some code in the referenced pull requests may have been updated later by additional patches during the beta release process.
If you would like to review all changes, review the code diff between the 9.0 branch and the 10.0 release: https://github.com/laravel/cashier/compare/9.0...v10.0.0
The following libraries were bumped to new minimum versions:
- The minimum Laravel version is now v5.8
- The minimum Symfony dependencies are now v4.3
- The minimum Stripe SDK version is now v6.40
- The minimum Carbon version is now v2.0
PR: laravel#643
The Stripe API version is now fixed by Cashier. By controlling the API version within Cashier, we can more easily prevent bugs due to API drift and update to new API versions gradually.
PR: laravel#653
The STRIPE_KEY environment variable is now always used as the publishable key and the STRIPE_SECRET environment variable is always used as the secret key.
PR: laravel#663
Just like in other Laravel packages, Cashier's migrations now ship with the package. These migrations are automatically registered and will be executed when you run php artisan migrate. If you have already run these migrations and want to disable additional migration being executed by Cashier, call Cashier::ignoreMigrations(); from the register method in your AppServiceProvider.
PR: laravel#690
Cashier now ships with a dedicated configuration file like many other first-party Laravel packages. Settings that were previously stored in the services.php configuration file have been transferred to the new cashier configuration file. In addition, many methods from the Cashier class have been created as configuration options within this file.
The STRIPE_MODEL environment variable has been renamed to CASHIER_MODEL.
PR: laravel#667
Any payment action will now throw an exception when a payment either fails or when the payment requires a secondary confirmation action in order to be completed. This applies to single charges, invoicing customers, subscribing to a new plan, or swapping plans. After catching these exceptions, you have several options for how to properly handle them. You can either let Stripe handle everything for you (you may configure this in the Stripe dashboard) or use the new, built-in payment confirmation page that is included with Cashier.
use Laravel\Cashier\Exceptions\IncompletePayment;
try {
$subscription = $user->newSubscription('default', $planId)
->create($paymentMethod);
} catch (IncompletePayment $exception) {
return redirect()->route(
'cashier.payment',
[$exception->payment->id, 'redirect' => route('home')]
);
}The IncompletePayment exception above could be an instance of a PaymentFailure when a card failure occurred or an instance of PaymentActionRequired when a secondary confirmation action is needed to complete the payment. In the example above, the user is redirected to a new, dedicated payment page which ships with Cashier. Here, the user can confirm their payment details and fulfill the secondary action (such as 3D Secure). After confirming their payment, the user will be redirected to the URL provided in the redirect route parameter.
Exceptions may be thrown for the following methods: charge, invoiceFor, and invoice on the Billable user. When handling subscriptions, the create method and swap methods may throw exceptions. The payment page provided by Cashier offers an easy transition to handling the new European SCA requirements.
If you would like to let Stripe host your payment verification pages, you may configure this in your Stripe settings. However, you should still handle payment exceptions in your application and inform the user they will receive an email with further payment confirmation instructions.
In addition, the subscription create method on the subscription builder previously immediately canceled any subscription with an incomplete or incomplete_expired status and threw a SubscriptionCreationFailed exception when a subscription could not be created. This has been replaced with the behavior described above and the SubscriptionCreationFailed exception has been removed.
A new stripe_status database column has been introduced for the subscriptions table, which corresponds with and is kept in sync via webhooks with the subscription status provided by Stripe. You can add this column to your subscriptions table using the migration below:
Schema::table('subscriptions', function (Blueprint $table) {
$table->string('stripe_status')->nullable();
});When a subscription is put into an incomplete_expired state, Cashier will automatically delete it from the database. More information on subscription statuses can be found here: https://stripe.com/docs/billing/lifecycle
PR: laravel#707
During subscription operations that fail and require additional payment configuration, a subscription will receive a status of incomplete or past_due. When this happens, you will need to inform the user that their payment requires additional confirmation.
You can determine if a user needs to confirm a payment using the new hasIncompletePayment method provided by the Billable trait. If the user has an incomplete payment, you may use the latestPayment method on the Subscription model to retrieve the latest failed payment and redirect the user to Cashier's payment confirmation screen:
@if ($user->hasIncompletePayment())
<a href="{{ route('cashier.payment', $user->subscription()->latestPayment()->id) }}">
Please confirm your payment.
</a>
@endifWhen a subscription is in an incomplete state, no plan changes can occur and an
SubscriptionUpdateFailureexception will occur when you try to call theswaporupdateQuantitymethods.
If you have enabled Stripe's built-in payment confirmation notifications then you do not need to configure the Cashier payment confirmation notifications.
Since SCA regulations require customers to occasionally verify their payment details even while their subscription is active, Cashier can send a payment notification to the customer when off-session payment confirmation is required. For example, this may occur when a subscription is renewing. Cashier's payment notification can be enabled by setting the CASHIER_PAYMENT_NOTIFICATION environment variable to a notification class. By default, this notification is disabled. Of course, Cashier includes a notification class you may use for this purpose, but you are free to provide your own notification class if desired:
CASHIER_PAYMENT_NOTIFICATION=Laravel\Cashier\Notifications\ConfirmPayment
To ensure that off-session payment confirmation notifications are delivered, verify that Stripe webhooks are configured for your application and the invoice.payment_action_required webhook is enabled in your Stripe dashboard.
PR: laravel#696
PR: laravel#701
Cashier has migrated to the new recommended Stripe Payment Methods API. This API effectively replaces the former Sources and Tokens API. At the moment, the Payment Methods API only supports cards but support for all of the other payment flows is planned.
Payment Methods are backwards compatible with the Sources and Tokens APIs, meaning that if you've saved cards as a source on a customer, they can be retrieved with the new Payment Methods API. However, at the moment there isn't a way to retrieve the default source from a customer through the Payment Methods API. Therefore, the defaultPaymentMethod method on the Billable user will return an instance of a Stripe\Card or Stripe\BankAccount if no default Payment Method could be found.
It's important to note that any default source set on a customer will still continue to work when creating new subscriptions. However, considering new SCA regulations which take affect September 2019, it's important that you update your integration to the new Payment Methods API as soon as possible and do not use the Sources or Tokens APIs any longer. In fact, if your users do not have a Laravel\Cashier\PaymentMethod attached to their account, you may wish to create one before creating a new subscription:
use Stripe\Card as StripeCard;
use Stripe\BankAccount as StripeBankAccount;
$defaultPaymentMethod = $user->defaultPaymentMethod();
if ($defaultPaymentMethod instanceof StripeCard ||
$defaultPaymentMethod instanceof StripeBankAccount) {
// Gather payment method and store it using new payment method APIs...
}Due to these changes, the Laravel\Cashier\Card class has been replaced with Laravel\Cashier\PaymentMethod class and the old card methods on the Billable trait were removed.
For more information regarding storing payment methods, review the Setup Intents documentation below.
PR: laravel#700
When storing payment methods, you should now use the Stripe Setup Intent API if you want to ensure your off-session recurring payments for your subscription keep working and do not trigger secondary payment confirmation actions.
To learn more about Setup Intents and creating payment methods for subscription billing or single charges, review the full Cashier documentation.
PR: laravel#697
The charge method now requires a payment method identifier instead of a token. You will need to update your Stripe.js integration to retrieve a payment method identifier instead of a source token. "Payment methods" are now Stripe's recommended way of dealing with customer payment information. More information about payments can be found in the official Stripe documentation.
Because Stripe doesn't offer a way to set a default payment method for single charges, the charge method now explicitly requires a payment method identifier as its second parameter:
$user->charge(1000, $paymentMethod);You can retrieve a payment method by implementing the new payment method Stripe.js integration.
PR: laravel#672
Because of updates in Stripe's recommended payment and subscription handling, properly handling Stripe's webhooks is now required in order to use Cashier. Thankfully, Cashier provides a controller which will properly handle these webhooks for you. You can read more about enabling webhooks in the full Cashier documentation.
The Cashier webhook handler route is now automatically registered for you and does not need to be manually added to your routes file anymore.
PR: laravel#685 PR: laravel#711 PR: laravel#690
Cashier now uses the moneyphp/money library to format currency values for display on invoices. Because of this, the useCurrencySymbol, usesCurrencySymbol and guessCurrencySymbol methods have been removed.
The useCurrency method has been replaced by a configuration option in the new Cashier configuration file and the usesCurrency method has been removed.
In addition, all raw methods on the Invoice object now return integers instead of floats. These integers represent money values in cents.
All invoice methods in Cashier now return an instance of Laravel\Cashier\Invoice instead of a Stripe\Invoice object.
PR: laravel#620
The swap method now accepts an $options argument.
PR: laravel#710
The swap method will no longer automatically invoice the customer. Instead, a dedicated swapAndInvoice method has been added to Cashier. The swapAndInvoice method may be used if you want to immediately invoice a customer when they change their plan.
PR: laravel#682
The following methods now require that the Billable user has an associated Stripe customer account created by your application: tab, invoice, upcomingInvoice, invoices, applyCoupon. An exception will be thrown if you attempt to call these methods without first creating a Stripe customer account for the user.
In their 2019-03-14 API update, Stripe changed the way they handle new subscriptions when card payment fails. Instead of letting the creation of the subscription fail, the subscription is failed with an "incomplete" status. Because of this a Cashier customer will always get a successful subscription. Previously a card exception was thrown.
To accommodate for this new behavior from now on Cashier will cancel that subscription immediately and throw a custom SubscriptionCreationFailed exception when a subscription is created with an "incomplete" or "incomplete_expired" status. We've decided to do this because in general you want to let a customer only start using your product when payment was received.
If you were relying on catching the \Stripe\Error\Card exception before you should now rely on catching the Laravel\Cashier\Exceptions\SubscriptionCreationFailed exception instead.
Previously, when a user attempted to change subscription plans and their payment failed, the resulting exception bubbled up to the end user and the update to the subscription in the application was not performed. However, the subscription was still updated in Stripe itself resulting in the application and Stripe becoming out of sync.
However, Cashier will now catch the payment failure exception while allowing the plan swap to continue. The payment failure will be handled by Stripe and Stripe may attempt to retry the payment at a later time. If the payment fails during the final retry attempt, Stripe will execute the action you have configured in your billing settings: https://stripe.com/docs/billing/lifecycle#settings
Therefore, you should ensure you have configured Cashier to handle Stripe's webhooks. When configured properly, this will allow Cashier to mark the subscription as cancelled when the final payment retry attempt fails and Stripe notifies your application via a webhook request. Please refer to our instructions for setting up Stripe webhooks with Cashier..
Like the latest releases of the Laravel framework, Laravel Cashier now requires PHP >= 7.1.3. We encourage you to upgrade to the latest versions of PHP and Laravel before upgrading to Cashier 9.0.
The updateCard call was extracted from the createAsStripeCustomer method on the Billable trait in PR #588. In addition, the $token parameter was removed.
If you were calling the createAsStripeCustomer method directly you now should call the updateCard method separately after calling the createAsStripeCustomer method. This provides the opportunity for more granularity when handling errors for the two calls.
Instead of calling the Stripe API to verify incoming webhook events, Cashier now only uses webhook signatures to verify that events it receives are authentic as of PR #591.
The VerifyWebhookSignature middleware is now automatically added to the WebhookController if the services.stripe.webhook.secret value is set in your services.php configuration file. By default, this configuration value uses the STRIPE_WEBHOOK_SECRET environment variable.
If you manually added the VerifyWebhookSignature middleware to your Cashier webhook route, you may remove it since it will now be added automatically.
If you were using the CASHIER_ENV environment variable to test incoming webhooks, you should set the STRIPE_WEBHOOK_SECRET environment variable to null to achieve the same behavior.
More information about verifying webhooks can be found in the Cashier documentation.