Stripe checkout event for failed payments

I have a paid membership site which takes payments via Stripe Checkout (server integration). When a user registers, they are redirected to the Stripe checkout (with their ID passed as the ‘client_reference_id’) where they enter their card details. For the checkout fulfillment, I have a webhook setup that is linked to the event ‘checkout.session.complete‘.

Everything is working fine, the webhook triggers and the endpoint processes the data and marks the corresponding account as activated, sends an email to the account holder as well as the site admin to let them both know the account has been created and a payment has been successful.

However, if a payment fails, I don’t know what event to attach to the webhook to detect failed payments via Stripe Checkout. The only checkout event documented is ‘checkout.session.complete’, there isn’t one for something like ‘checkout.session.failed’. There’s ‘invoice.payment_failed’ but this is used in subscriptions not one-off checkout payments.

We’re wanting to basically notify the site admin when a payment fails so they are aware an account has been created but it still awaiting payment.

Is there a checkout event I’m missing or another way to go about finding failed checkout transactions?

Answer

To charge a credit or a debit card, you create a Charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique, random ID.

— From the Stripe API Documentation.

You can then detect a webhook response of charge.failed to show that an attempted use of a charge object has failed.

Stripe used to be very cleanly documented, but they’ve lost their way a little, recently.

Stripe card payments ALWAYS use Charge objects, sometimes these are set by you (invoices, subscriptions, etc.) and sometimes these are set behind the scenes by Stripe (“Checkout Process”, etc) — but they are always set, so your webhook can always detect a charge.failed event.


Addendum

This does work, however, since the client_reference_id is not in the charge.failed data, I can’t link the failed payment to a specific account anyway. But in regards to my actual question, this event does work and is the correct answer, just unfortunate that it doesn’t solve my specific situation.

To solve this; either using the Stipe interface or by coding:

1) Create a Customer object and keep some sort of record of this customer Id.

2) When the Stripe Charge runs, an associated $charge->customer is set. This is available to your webhook.

3) When the webhook result appears, use this (typically) $event->data->object->customer value to cross reference the charge with the correct customer on your server.

4) As mentioned in comments, Stripe Webhook Testing does not populate the webhooks with example data such as ->customer:-(