Laravel Subscriptions
This episode is for members only

Sign up to access "Laravel Subscriptions" right now.

Get started
Already a member? Sign in to continue
Playing
25. Dealing with past due payments

Episodes

0%
Your progress
  • Total: 2h 38m
  • Played: 0m
  • Remaining: 2h 38m
Join or sign in to track your progress

Transcript

00:00
At some point, payments for your customer's subscriptions are going to fail. And that's going to put the subscription into a past due status.
00:08
Let's take a look at what happens with our application when that happens. So I've just gone ahead and created a fresh subscription. I have it open here in Stripe dashboard. What we're going to do is run a simulation on this subscription to put this
00:22
into a failing past due status. So we're basically going to make the card decline. Let's just remind ourselves what this looks like in the database. And you can see the Stripe status is set to active.
00:35
That means that I have full access to the application so I can access this protected area. OK, let's go ahead and grab a test card number that is going to fail. So what we want to do is come down to the decline section.
00:49
We don't want to use a generic decline to update the card details. What we want to do here is come down to this decline after attaching so we can successfully update the customer's card with this. But on the next payment is going to fail.
01:03
So let's go over to our actual application and we'll just do this the standard way rather than with the Stripe dashboard. So let's go over to the managed subscription section and let's go ahead and update our card.
01:14
So once this is loaded, let's go ahead and just change our payment method over. So we're going to add a payment method here. And let's add the payment method we just copied from the Stripe docs. And we can just add any expiry, any security code and any postal code in here.
01:31
OK, let's just go ahead and make this valid. And let's go ahead and add the card. So that's going to successfully add. But the next time this user makes a payment as part of the subscription
01:43
automatically, it's going to go ahead and fail. How do we do that? Well, like I just said, we can use a simulation for this subscription. So it's currently in the active state.
01:53
Let's go ahead and run a simulation on this. And of course, we're going to choose a future date and time. So I signed up on the 2nd of October. Let's go over to the 2nd or 3rd of November and see what happens
02:04
when we advance the time here. So we're going to click on that. That's going to go ahead and run the simulation on this subscription. It might take a little while.
02:11
So we're just going to wait for this to finish. And once it's done, because that payment will now fail, it should be put into a past due state. OK, so that's just refreshing now.
02:20
So let's just wait for this. And you can see it is now overdue. So with the webhook being sent through to our application, what's now going to happen is that Stripe status will have been set to past due.
02:33
Now, by default with Laravel Cashier, if we just come over to our application, we just go back to our account here. You can see it now looks like the user does not have access, even though they technically should, because we want to give them a grace
02:46
period for them to actually update their car details. Now, Stripe will handle sending of the emails to let the user know that their card payment has failed. But we don't want to kick them out of our subscription
02:57
immediately if their next payment fails. We should still keep the subscription active for a while to give them a chance to update their card. So the question is, how do we get around this?
03:08
Well, the first thing that we want to do is head over and make sure that we allow past due subscriptions to remain active. To do this, we're going to head over to any of these service providers in our application.
03:20
Let's just use the app service provider that we added this blade directive to earlier. And let's go ahead and use the cashier class. And let's go ahead and say, keep past due subscriptions active.
03:35
That will go ahead and tell cashier that we want to keep these active, even if the card payment's failing. Let's go back over to the browser, give this a refresh. And you can see we are still in so we can still access everything.
03:48
But of course, we still need to update our card payment or eventually this is going to get cancelled. If this continues to be overdue and Stripe doesn't collect a payment, it will send the cancellation webhook down
04:01
and will be kicked out of our subscription within our app. Now, what you might want to do is somewhere in your app show the user that their payment is failing. So we could do that anywhere.
04:11
But let's go ahead and do that over in the authenticated layout or in the navigation partial where we added in the trial information. So we'll just do pretty much exactly the same thing. But we'll just do this down here.
04:24
And of course, you can add this to anywhere. You could create a huge banner at the top of your application if you wanted to. It's entirely up to you. So let's go ahead and create out another if statement just in here.
04:33
And let's use the subscription from the user. So remember, the user may not be authenticated. So let's make sure we say auth user and then optionally check this. And there's a couple of ways to do this.
04:45
We could either grab the subscription by the type if we've chosen a different default, and then we can say has incomplete payment. So that will tell us if we're in a past due or incomplete state, or we can do this directly on the user itself if we're not too worried
05:03
about specifically picking out the subscription name. So if we have a incomplete payment, let's go ahead and just grab the container that we created earlier. And let's go ahead and make this into something
05:15
that we would actually want to use. So let's say your payment is failing and let's say update your details. So we'll create out an anchor in here and just say update card. And we'll link through to that in a minute.
05:28
Let's just make sure it displays first of all. OK, great. So we know that we're in a past due state that is now showing this. Let's link through to the user to update their card.
05:37
So let's give this a text of indigo 500 or let's say 500. And let's go ahead and link this through to somewhere. So what we could actually do is just link this directly through to the portal that we created earlier.
05:50
So we have a subscription portal route here. Let's go back over and just hook this up so the user can go directly in and update their details. So let's go over and straight over to the subscription portal.
06:03
OK, so let's go ahead and hit update card. That's going to send us directly over to the portal. Let's go ahead and update this now. So you can see it shows in the Stripe dashboard as well.
06:12
So let's go and make this payment here the default. So let's go and pay the failed amount. Stripe will automatically collect that otherwise. But let's go ahead and just manually do this.
06:21
Let's wait for this to finish. And what's going to happen now is another webhook is going to be sent through. Cashier will pick this up and that will then go ahead and put the user back into an active state.
06:32
And you can see the message at the top has disappeared here now. So this is something that's really easy to overlook, but it's really important to not kick the user out if with one failing payment and also let them know so they can go ahead and update their card details.

Episode summary

In this episode, we dive into what happens when a customer’s subscription payment fails and how to handle the resulting "past due" status in your Laravel app using Cashier and Stripe.

First, we simulate a failed payment by using a special test card in the Stripe dashboard, showing how the subscription status in your database changes to "past due". We also walk through how, by default, your Laravel app might immediately restrict access for users whose payment fails—which isn’t always the best user experience!

To address this, we update our app to keep past due subscriptions active for a grace period. This gives customers a chance to resolve their payment issue before losing access. We show exactly how to enable this in your service provider code.

Next, we improve the user experience by adding a notification in the app’s UI whenever a payment failure occurs. Users get a prompt to update their card details, linked directly to the appropriate page (or the subscription portal), making it easy for them to fix the problem.

Finally, we test things end-to-end: once the payment is resolved, Stripe and Cashier will update the user’s subscription status automatically, and our UI banner disappears. Throughout the episode, we highlight best practices for balancing access control with a friendly recovery process for failing payments.

Episode discussion

No comments, yet. Be the first!