> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Retries

> Handle payment retries when an auto-charge fails for Razorpay Subscriptions. Check different failure scenarios and handle them using webhooks.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
  <span>🇸🇬 Singapore</span>
  <span>🇺🇸 United States</span>
</div>

Recurring payments for a Subscription are auto-debited based on the scheduled day that you defined. However, these payments could fail.

## Reasons for Payment Failures

* The card has expired.
* The bank has blocked the card.
* The customer's account has insufficient balance.
* The customer has cancelled the mandate from their end.

## What Happens in Case of a Payment Failure

Here is the Subscription flow if a payment fails:

1. The Subscription will move to the `pending` state.
2. You are notified about it via our webhooks. We automatically retry the payment on the following day.
   * We automatically charge the last invoice if the customer changes the card when the Subscription is in the `pending` state.
   * If this charge is successful, the Subscription moves to the `active` state.
3. If the payment fails after all retries, the Subscription will move to the `halted` state.
   * If the customer successfully changes the card details when a Subscription is in the `halted` state, it moves to the `active` state. Invoices for such Subscriptions are still created. However, we will not charge these invoices. You will have to charge them manually.

<Info>
  **Handy Tips**

  This process will not affect the charge cycle for the subsequent months.
</Info>

### Notifications

* If you have enabled the `subscription.pending` and `subscription.halted` webhook, you receive notifications every time a Subscription moves to one of the above-mentioned 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 details associated with the Subscription.

## Retry Model for Cards

In failure scenarios, we automatically retry the payment the next day without your interference.

In a T+3 days cycle, we will retry the payment thrice. 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 charge day.
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 on T+1 day.
4. If the charge fails again, we automatically reattempt the charge two more times on T+2 and T+3 days, respectively.
5. If the charge still fails, the Subscription moves to the `halted` state.

## Handle Failed Charge (Cards)

There are two ways to handle a failed charge:

* [Manually attempt to charge the same card](#manual-charge-on-same-card)
* [Change the card details associated with the Subscription](#change-card-linked-to-subscription)

### Manual Charge on 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.

<Warning>
  **Watch Out!**

  Manual charging of a domestic card is not supported.
</Warning>

**Example** <br />
The customer's account might have an insufficient balance when you attempt to auto-charge. When they receive the payment failure email, they add money to their account and inform you about this. You can [attempt a manual charge on the invoice using the Dashboard](/docs/sg/payments/subscriptions/manually-charge-card).

* If you have enabled the `subscription.pending` and `subscription.halted` webhook, you receive notifications every time a Subscription moves to one of the above-mentioned 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 details associated with the Subscription.

### Change Card Linked to Subscription

1. 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.
2. You can ask the customer to change the card linked to the Subscription.

<AccordionGroup>
  <Accordion title="Change Card Using Checkout">
    You can ask the customer to change the card details associated with the Subscription on your checkout using our APIs. Use the `subscription_card_change` parameter to control this feature:

    * 1 : Allow the customer to change the card details from your checkout
    * 0 : Do not allow the customer to change the card details from your checkout

    <CodeGroup>
      ```html Checkout with handler function theme={null}
      <button id = "rzp-button1">Pay</button>
      <script src = "https://checkout.razorpay.com/v1/checkout.js"></script>
      <script>
        var options = {
          "key": "key_id",
          "subscription_id": "sub_00000000000001",
          "name": "Acme Corp.",
          "description": "Monthly Test Plan",
          "image": "/your_logo.jpg",
          "subscription_card_change": true,
          "handler": function(response) {
            alert(response.razorpay_payment_id),
            alert(response.razorpay_subscription_id),
            alert(response.razorpay_signature);
          },
          "prefill": {
            "name": "<name>",
            "email": "<email>",
            "contact": "<phone>"
          },
          "notes": {
            "note_key_1": "Tea. Earl Grey. Hot",
            "note_key_2": "Make it so."
          },
          "theme": {
            "color": "#F37254"
          }
        };
      var rzp1 = new Razorpay(options);
      document.getElementById('rzp-button1').onclick = function(e) {
        rzp1.open();
        e.preventDefault();
      }
      </script>
      ```

      ```html Manual checkout with callback URL theme={null}
      <button id = "rzp-button1">Pay</button>
      <script src = "https://checkout.razorpay.com/v1/checkout.js"></script>
      <script>
        var options = {
          "key": "key_id",
          "subscription_id": "sub_00000000000001",
          "name": "Acme Corp.",
          "description": "Monthly Test Plan",
          "image": "/your_logo.jpg",
          "subscription_card_change": true,
          "callback_url": "https://eneqd3r9zrjok.x.pipedream.net/",
          "prefill": {
            "name": "<name>",
            "email": "<email>",
            "contact": "<phone>"
          },
          "notes": {
            "note_key_1": "Tea. Earl Grey. Hot",
            "note_key_2": "Make it so."
          },
          "theme": {
            "color": "#F37254"
          }
        };
      var rzp1 = new Razorpay(options);
      document.getElementById('rzp-button1').onclick = function(e) {
        rzp1.open();
        e.preventDefault();
      }
      </script>
      ```
    </CodeGroup>

    <Info>
      **Handler Function vs Callback URL**

      | Handler Function                                                                                                                                                                                                                                  | Callback URL                                                                                                                                                                       |
      | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | 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. | 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. |
    </Info>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update Payment Method On Our Hosted Page">
    You can use our ready-made hosted page solution to handle payment failures when you attempt an auto-charge. 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. Customers can either retry the payment on the same card, update the card details, or change the payment method to wallet. The hosted page handles these actions seamlessly.

    The following table lists the supported payment method change.

    | Current Payment Method | Change to Card | Change to Wallet (Touch'n Go) |
    | ---------------------- | -------------- | ----------------------------- |
    | Card                   | Yes            | Yes                           |
    | Wallet (Touch'n Go)    | Yes            | Yes                           |

    Use the Dashboard status filter to search for `halted` and `pending` Subscriptions. You can send the Subscription link to the respective customers to clear dues and make those Subscriptions active.
  </Accordion>
</AccordionGroup>

### Related Information

* [Subscription Workflow](/docs/sg/payments/subscriptions/workflow)
* [Subscription States](/docs/sg/payments/subscriptions/states)
* [Create Subscriptions](/docs/sg/payments/subscriptions/create)
* [Test Subscriptions](/docs/sg/payments/subscriptions/test)
* [Subscriptions APIs](/docs/sg/payments/subscriptions/apis)