Recover failed Razorpay payments with a fresh payment link

Run this every time Razorpay tells us a payment has failed. Set it up on a Razorpay webhook subscribed to the payment.failed event, and read the failed payment id out of the webhook body (payload.payment.entity.id).

Start by calling Razorpay Fetch a Payment with that id, so I am working from the authoritative record rather than the webhook snapshot. From the payment I need the amount and currency, the order id, the description, the customer email and contact number, the notes, and the whole error block: error_code, error_description, error_source, error_step and error_reason. Razorpay amounts are integers in paise, so divide by 100 whenever money is shown to a person. If there is an order id and the payment description is thin, call Razorpay Fetch an Order to get a better name for what the customer was actually buying.

Then judge what kind of failure this was, reading the error fields rather than matching a fixed list of codes. Treat it as recoverable when the customer could plausibly pay again right now: not enough funds, a bank or gateway timeout or outage, an issuer that was temporarily unavailable, an OTP that expired or was never entered, an abandoned or cancelled attempt, or a one off decline with no fraud signal. Treat it as unrecoverable when retrying would be pointless or unwise: a card reported stolen or lost, a blocked or restricted card, a suspected fraud decline, or an account the issuer has closed. If the error text is genuinely ambiguous, take the recoverable path but say so plainly in the Slack message when one gets posted.

For a recoverable failure, create a fresh way to pay using Razorpay Create a Payment Link for exactly the same amount and currency as the failed payment. Prefill the customer name, email and contact from the payment record, write a description that names the item the customer was buying, turn reminders on, and set the link to expire in 72 hours (keep that expiry easy to change). Stamp the original payment id into the link notes, for example notes.original_payment_id, along with the original order id and the error code, so a recovered payment can always be traced back to the failure it came from.

Then send the customer a short recovery email with Gmail Send a Message. Keep it to three or four friendly sentences and never blame them or imply their card was rejected: say the payment did not go through, name the item, and make the new payment link the one obvious next step. Put a stable marker in the subject line so the email can be recognised later, ideally the order id, falling back to the failed payment id when there is no order. If the customer has a phone number and no usable email, or SMS is simply the better channel for this audience, use Razorpay Send or Resend Payment Link Notification with the SMS medium instead of, or alongside, the email.

Before anything goes to the customer, make sure I am not chasing the same person twice in one day about the same order. Use Gmail List Messages with a query along the lines of in:sent to:<customer email> newer_than:1d combined with the order id marker, and if a recovery email for that order already went out in the last 24 hours, skip the email entirely. Skipping the email never skips the Slack side of this workflow.

For an unrecoverable failure, do not email the customer at all and do not create a payment link. Post to Slack with Send a Message instead, so a human can decide what to do: customer name and email, the amount in rupees, the item, the payment id, the error code and reason, and a one line read on why this looks unrecoverable. Also post to Slack whenever the failed amount is above a configurable high value threshold (default it to 25,000 rupees, which is 2,500,000 paise) even when the failure was recoverable and a link has already gone out. In that case the message should say that a recovery link was created and sent, and carry the new link so the account owner can follow up personally.

Handle the edges sensibly. If the payment has neither an email nor a phone number, skip the customer outreach and post to Slack. If creating the payment link fails, never send an email promising a link that does not exist: post that failure to Slack instead. Post at most one Slack message per failed payment rather than one per branch, and keep it short enough to read in the channel without expanding it.