Recover failed payments over iMessage

When a card is declined, your server texts the customer a heads-up with no link, from your own number. Once they reply, you send the billing-page link, which is tappable by then.

Pro is $49/month per number. Limits apply.

# renewalsyour server
Stripe9:12 AM

invoice.payment_failed for Jamie L., card ending 4021.

Your server9:12 AM

Sent the heads-up with POST /api/imessage/send. No link in it.

message.received9:13 AM

Jamie said yes. Your server sent the billing link.

Stripe9:15 AM

invoice.paid. A tapback on Jamie’s last text and one line of confirmation.

A failed renewal, start to finish
Tallyroom
Today 9:12 AM
Hi Jamie, heads up: the card ending 4021 was declined for your Tallyroom renewal. Want me to send a secure link to update it?
oh yeah new card. send it
Here you go, takes 30 seconds: tallyroom.example/billing
done
Got it, you’re all set.

Ask first, then send the link.

An Apple phone will not open a link from a sender it does not know. Your first text asks a question, and the link goes out once the customer replies.

Tallyroom
Today 9:12 AM
Hi Jamie, the card ending 4021 was declined. Update it here: tallyroom.example/billing
Hi Jamie, heads up: the card ending 4021 was declined for your Tallyroom renewal. Want me to send a secure link to update it?
yes please
Here you go: tallyroom.example/billing
json
{"ok": true, "status": "message_sent",
 "warning": {"code": "link_not_tappable"}}
http
message.received  "yes please"
POST /api/imessage/send  { the link }

Only the first text counts toward your limit.

It counts as a new contact only if your number has never messaged that customer. The link, a follow-up and the tapback never do.

Heads-ups sent per dayIllustrative
0Day 1
0Day 2
0Day 3
0Day 4
0Day 5
0Day 6
0Day 7
0Day 8
0Day 9

Anniversary billing spreads renewals across the month, so failures arrive a few a day, usually within Pro’s 5.

How failed payment recovery works

A failed-payment event triggers one question with no link. The link follows the customer’s answer, and the paid event closes the thread with a tapback.

  1. Check consentStripe fires invoice.payment_failed, and most billing systems have an equivalent event. Your handler checks that the customer agreed to account notifications by text. Customers with no record get the email instead.
  2. Send one heads-up per invoiceStripe sends the same event for retry attempts, with an attempt_count, and its recommended Smart Retries default is 8 tries within 2 weeks. Key the heads-up on the invoice ID so the customer gets one text per invoice, not one per retry.
  3. Ask, without a linkPOST /api/imessage/send sends the question. Your brand name and photo, if you set them, go with the first message, and the card’s last four digits tell the customer which account you mean.
  4. Send the link after they agreeThe reply reaches your webhook as message.received about 1 to 2 seconds after it lands on the line. Your handler sends the billing link, which is tappable now that the customer has replied.
  5. Confirm with a tapbackWhen invoice.paid arrives, POST /api/imessage/reactions puts a like on the customer’s last message and you send one line of confirmation. If they updated the card without paying the invoice, that event waits for Stripe’s next retry. If they paid without replying, send nothing.
  6. Follow up once, at mostIf there is no reply after a couple of days and the invoice is still open, send one more text with no link. Then leave the rest to email.
python
def heads_up(invoice: dict) -> None:
    if invoice.get("billing_reason") != "subscription_cycle":
        return                                 # a failed signup, not a renewal
    c = customer_for(invoice["customer"])      # your DB: number, text consent, card
    if not c or not c.account_texts_ok or c.open_invoice == invoice["id"]:
        return                                 # no consent, or a retry we already asked about
    c.open_case(invoice["id"])
    zs("/api/imessage/send", {"to": c.phone, "text": f"Hi {c.first_name}, heads up: the card "
        f"ending {c.card_last4} was declined for your Tallyroom renewal. "
        "Want me to send a secure link to update it?"})

def on_reply(msg: dict) -> None:               # from the message.received webhook
    c = customer_for_number(msg["handle"])
    if not c or not c.open_invoice:
        return
    c.last_reply_id = msg["id"]                # the bubble the tapback goes on
    if not c.link_sent and YES.search(msg.get("text") or ""):
        c.link_sent = True                     # your URL; it opens a portal session on tap
        zs("/api/imessage/send", {"to": msg["handle"],
            "text": f"Here you go, takes 30 seconds: {c.billing_link()}"})

def paid(invoice: dict) -> None:               # from Stripe's invoice.paid
    c = customer_for(invoice["customer"])
    if c and c.open_invoice == invoice["id"] and c.last_reply_id:
        zs("/api/imessage/reactions", {"message_id": c.last_reply_id, "reaction": "like"})
        zs("/api/imessage/send", {"to": c.phone, "text": "Got it, you're all set."})
        c.close_case()

One small service handles two webhooks. Stripe’s opens and closes each case, and ours carries the reply. Webhooks, step by step has the signature check. The full guide has the whole service.

Limits and rules

A new contact is a handle the line delivers a text, voice message or photo to first. Reactions, typing, profile shares and failed sends never count. Each number handles up to 10,000 messages a day with known contacts.

Limit, per numberProGrowth
New contacts per day (3 AM to 3 AM Eastern)525+
Unanswered messages to one customer2, then 403 awaiting_reply2, then 403 awaiting_reply

Consent comes first

Text only customers who agreed to account notifications by text, with a record you can show. Your first message says who you are. A text with the word STOP in it, or a clear request like “take me off your list”, opts the customer out on every number on your account, and only START opts them back in. After that, sends and tapbacks return 403 recipient_opted_out, so email carries the rest. See how STOP works. This is not legal advice.

Never ask for card numbers in the thread

The card is entered only on the billing page. The PCI Security Standards Council says Requirement 4.2.2 prohibits sending unprotected card numbers “via end-user messaging technologies”, SMS and chat included. Our terms say content may not be encrypted and we cannot guarantee communication privacy. See how we secure the API and webhooks.

Why the link waits

Our docs say an Apple phone will not open links from an unknown sender until they reply or save your number. Why first-message links are not tappable has the details, and Screen Unknown Senders on iOS 26 can hide a cold first text altogether.

Calendar billing

Billing on the 1st puts every failure on one morning. Say 45 renewals fail, all for customers your number has never messaged. Pro sends 5 and hits the daily cap, and the allowance resets at 3 AM Eastern, so the other 40 go out 5 a day over the next eight days, at a sensible hour where each customer lives. Check that each queued invoice is still unpaid first, because a retry may have succeeded. On Growth, three numbers working as one send 9 per 15 minutes and clear all 45 in a little over an hour.

SMS fallback

Eligible plain-text payment reminders can reach customers on Android from the same number.

Not a fit

Customers did not agree to account texts, because a billing relationship alone is not a consent record. You have no card-update page to link. You would collect card numbers by text, which you should never do. The App Store bills the subscription.

Before and after a failure

Before a renewal fails, trial-ending and renewal reminders or a keep, skip or swap question can head it off. For customers leaving on purpose, see texting the founder from your cancel flow.

A flat price per number

No per-message fees, and a 30-day money-back guarantee on Pro. This flow uses no credits.

Pro

For failed-payment texts and the replies they get

$49 /mo per number

  • 5 new contacts a day per number
  • Only the heads-up can count against it
  • No per-message fees
  • 30-day money-back guarantee
Get started

Questions

What if my code puts the link in the first text anyway?

It still goes out, and the send response adds warning.code: "link_not_tappable". The customer sees plain text they cannot tap, so ask first.

Can automatic retries fix an expired card?

Sometimes. Stripe tries to update saved cards through the card networks when a bank reissues one, where the issuer takes part. Otherwise a retry charges the same dead card, and only the customer can enter a new one.

Is a failed-payment text marketing?

Usually not. A declined-card notice is generally treated as a transactional account message, though the rules depend on wording and jurisdiction. Keep it to one heads-up and one follow-up, and leave discounts out, because an offer can turn it into marketing, which needs its own consent. This is not legal advice.

What if a customer texts their card number?

Do not repeat it. Point them to the billing page and scrub it from your webhook logs. Once the case is closed, DELETE /api/imessage/conversations/{handle} removes every stored row for that handle, though nothing already delivered is unsent, and your next text to them counts as a new contact again.

How many failed-payment texts can one number send a day?

On Pro, 5 heads-ups a day to customers your number has never messaged. On Growth, 25+ a day per number. The link, a follow-up and the tapback do not count, because the customer has replied by then.

What if the App Store bills the subscription?

This page does not fit that case. Apple’s docs say the App Store retries billing for up to 60 days, and the fix happens on the Manage Payments page in the customer’s account settings, not on a billing page of yours.

Start with one number

Get a number and send your first failed-payment text to your own phone.