How to email a customer when their Stripe payment fails

The short answer

When a payment for an invoice fails, Stripe sends an event called invoice.payment_failed. Stripe's own advice is to notify the customer. You can turn on Stripe's email, handle the event in your own code, or connect Stripe to Kicklace and let it write and send a note in your voice.

Whatever you pick, tell the customer quickly and plainly. A failed payment is usually an expired card, not someone leaving.

The plain way

Stripe's own email. In Stripe's revenue recovery settings, turn on "Send emails when card payments fail". Stripe then emails the customer after each failed payment, with a link to update their payment method, in your Stripe branding.

Your own webhook.

1. Add a webhook endpoint in Stripe that listens for invoice.payment_failed.
2. Check the signature on every request. Stripe signs each one in a Stripe-Signature header and needs the raw body untouched.
3. Return a 2xx fast and send the email after. Keep the event ids you have handled, because an event can arrive twice.

const event = stripe.webhooks.constructEvent(rawBody, signature, endpointSecret);

if (event.type === "invoice.payment_failed") {
  const invoice = event.data.object;
  // invoice.customer_email, invoice.attempt_count, invoice.hosted_invoice_url
}

The invoice carries the customer's email and name, the amount due, and a hosted page where they can pay. It also carries attempt_count, because Stripe retries a failed payment and reports those retries through this same event. Stripe's recommended Smart Retries default is 8 tries within 2 weeks, so decide whether you email on every attempt or only the first.

With Kicklace

1. Go to Settings → Connections → Stripe → Connect. It asks for one restricted key. In Stripe, create one with Write on Webhook Endpoints and Read on Customers, Subscriptions, Invoices, PaymentIntents, Products and Prices.
2. Paste it and press Connect. Kicklace adds its own webhook, called Kicklace, to your Stripe account and keeps the secret Stripe hands back. The key is locked away and never shown again.
3. Stripe's invoice.payment_failed now lands in Kicklace as a failed payment, and the subscription is marked past due. Kicklace finds the person by the email Stripe holds for the customer.
4. On your Lifecycle map, add a side road that starts from a failed payment. The first-run setup offers side roads like this, and the + at the top adds one later.
5. Write the email, or let Kicklace write it from your site. An email with no words yet has Write it for me.
6. Switch the sequence on. First Kicklace shows who would have got it over the last 30 days. Send yourself a test before you do.

A failed payment is an account email. It goes unless the address bounced or the person complained. Kicklace sends each email in a sequence to a person once, and a payment that clears on a retry takes them off the side road, so the sequence stops.

Kicklace only reads Stripe. It never charges anybody, and it does not retry payments: that stays with Stripe's own retry settings. Payments from Stripe lists every event Kicklace hears. See it on your own site in the demo, with no sign-up.

What the email should say

Say what happened, what to do, and what happens if nothing is done. No blame, no alarm.

Subject: Your payment didn't go through

Hi {{first_name}},

Your latest payment for [your app] did not go through. This is usually an expired card or a block from the bank, and it is quick to fix.

You can update your card here: [link to your billing page].

[Say what happens next and when, in your own words.] If you would like a hand, reply to this email.

[Your name]

Fill the brackets with your own details. A ready-made version is in the failed payment email template.

FAQ

Should I turn off Stripe's email?

Choose one. If Stripe's email and yours are both on, a customer gets two for the same failure. Stripe's is quick to switch on. Yours can sound like you.

Does Stripe retry the payment?

Yes, if you have retries on. Stripe recommends Smart Retries, and it will not retry some hard declines until the customer adds a new payment method. That is a good reason for the email to include a way to update the card.

What does it cost?

Kicklace is free up to 1,000 contacts, sending from its own address with your name on it. Your own domain is part of Starter, $25 a month. See pricing. Before cards fail, there is the trial ending email.