API ReferenceIntegrationsKnowledge Base

Payment Retries

Recurring payments for a subscription are auto-debited based on the scheduled day as defined by you. However, these payments could could fail. Listed below are some of the reasons these payments fail.

In such failure scenarios, the subscription is moved to the pending state. You are notified about the failed attempt via our webhooks. We automatically process a retry the next day without you having to take any action. If the payment fails on all retires, the subscription moves to the halted state.

If the customer changes the card while the subscription is in the pending state, we automatically attempt to charge the last invoice. If this charge is successful, the subscription moves to the active state.

If the customer successfully changes the card while the subscription is in halted state, the subscription moves to the active state. Invoices for a subscription are created even when the subscription is in the halted state. However, these invoices are not charged by us. You will have to charge these invoices manually.

Notifications#

If you have the subscription.pending and subscription.halted webhook events enabled, you receive notifications every time a subscription moves to one of these states. You can then decide to hold off the delivery of the service as per your business model.

We also send an email to the customer notifying them about the payment failure. This email contains a link that the customer can use to change the card that is associated with the subscription.

Retry Model - Example#

In failure scenarios, we automatically process a retry the next day without you having to take any action.

In a T+3 days cycle, we attempt retires three times. That is, once every day for 3 days, excluding the date of the charge. If the payment fails on all retires, the subscription moves to the halted state.

Below is the retry model:

  1. Let T=0 be the day when the charge was to be made.
  2. On T=0 we attempt to charge the card.
  3. If the charge fails, the subscription moves to the pending state and we automatically reattempt the charge again on T+1.
  4. If the charge fails again, we automatically reattempt the charge two more times on T+2 and T+3, respectively.
  5. If the charge still fails, the subscription moves to the halted state.

Handle Failed Charge#

There are two ways you can handle a failed charge:

Manual Charge on the Same Card#

When an auto-charge fails, you can manually attempt to charge the invoice as long as the invoice is in the issued state.

For example, the customer's account might have insufficient balance when the auto-charge is attempted. When they receive the payment failure email, they add money to their account and inform you about this. You can now attempt a manual charge on the invoice.

An authentication charge of ₹5 is made to authenticate the card. Once the manual charge is successful, the customer receives an email and you receive a webhook.

You can attempt a manual charge on the invoice using the Dashboard.

If you have the subscription.pending and subscription.halted webhook events enabled, you receive notifications every time a subscription moves to one of these states. You can then decide to hold off the delivery of the service as per your business model. We also send an email to the customer notifying them about the payment failure. This email contains a link that the customer can use to change the card that is associated with the subscription.

Change the Card Linked to the Subscription#

When an auto-charge fails, we send the customer an email about the payment failure. This email has a link that the customer can use to change the card linked to the subscription.

You can ask the customer to do this as well.

Change the Card via your Checkout#

You can ask the customer to change the card linked to the subscription via your checkout using our APIs. Use the subscription_card_change parameter to control this feature:

  • 1 = Allow the customer to change the card from your checkout
  • 0 = Do not allow the customer to change the card from your checkout

Handler Function vs Callback URL:

  • Handler Function:
    When you use the handler function, the response object of the successful payment (razorpay_payment_id, razorpay_order_id and razorpay_signature) is submitted to the Checkout Form. You need to collect these and send them to your server.
  • Callback URL:
    When you use a Callback URL, the response object of the successful payment (razorpay_payment_id, razorpay_order_id and razorpay_signature) is submitted to the Callback URL.

Change the Card via our Hosted Page#

You can use our ready-made hosted page solution to handle payment failures when an auto-charge is attempted. Here is how the hosted page handles payment failure:

  1. The customer is notified via email about the payment failure.
  2. The payment failure email contains a link that allows the customer to take further action on the failed payment.
  3. The action could either be retrying the payment on the same card or updating the card, both of which are handled seamlessly by the hosted page.

A sample hosted page is shown below:

Note:
To use our Hosted Page solution, pass 1 against the customer_notify parameter (that is, customer_notify=1) when creating the subscription via APIs.

Refer to the API reference page for more information.