4. Webhooks

Available in🇮🇳 India

Webhooks automatically notify your application when specific events occur. Instead of continuously polling APIs to check for updates, webhooks push notifications directly to your server when events happen. Integrating with webhooks is strongly recommended as it is the most efficient method for tracking payment and token status changes in real time.

Watch Out!Webhooks are delivered asynchronously in near real-time. Rely on webhooks for all automation. If a critical user-facing flow requires instant status, but the webhook notification has not arrived within the time mandated by your business needs, perform an immediate API Fetch call (Payments, Orders and Refunds) to verify the status.

To configure webhooks, go to the Razorpay Dashboard and set up the webhook URL for your account. Know more about Webhooks.

Check Token Status using Webhooks

You can use the below webhooks to check the status of the token (mandate).

Webhook Event	Description
`token.confirmed`	Indicates that the bank has completed the mandate registration. Once confirmed, you can execute subsequent payments as per your business needs.
`token.rejected`	Indicates that the mandate registration has been rejected. If rejected, you need to initiate the mandate registration again.
`token.cancelled`	Indicates the token has been cancelled, either by the customer from their UPI app or by the merchant via the Cancel Token API.
`token.paused`	Indicates the token has been paused by the customer from their UPI app or, for card tokens, from the bank’s mandate portal. No subsequent debits can be executed while the token is paused.

Token Confirmed

Indicates that the bank has completed the mandate registration. Once confirmed, you can execute subsequent payments as per your business needs.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "token.confirmed",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_FHhm0XTtJg9zqb",
        "entity": "token",
        "token": "BmwqwrkHZTlzVF",
        "bank": null,
        "wallet": null,
        "method": "upi",
        "vpa": {
          "username": "gaurav.kumar",
          "handle": "upi",
          "name": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "confirmed",
          "failure_reason": null
        },
        "auth_type": null,
        "mrn": null,
        "used_at": 1595456636,
        "created_at": 1595456636,
        "start_time": 1595456608,
        "dcc_enabled": false
      }
    }
  },
  "created_at": 1595456636
}

Token Rejected

Triggered during the mandate registration process, when the registration fails without completion.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "token.rejected",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_FHhm0XTtJg9zqb",
        "entity": "token",
        "token": "BmwqwrkHZTlzVF",
        "bank": null,
        "wallet": null,
        "method": "upi",
        "vpa": {
          "username": "gaurav.kumar",
          "handle": "upi",
          "name": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "rejected",
          "failure_reason": "Rejected by bank"
        },
        "auth_type": "upi",
        "mrn": null,
        "used_at": 1595456636,
        "created_at": 1595456636,
        "start_time": 1595456608,
        "dcc_enabled": false
      }
    }
  },
  "created_at": 1595456636
}

Token Cancelled

Triggered when a token is cancelled successfully. This can happen when the customer cancels the token from their UPI app or when the business cancels it via the Cancel Token API. When you call the Cancel Token API, the token first enters the cancellation_initiated state while Razorpay waits for NPCI and the customer’s bank to confirm the closure. The token.cancelled webhook is triggered only after NPCI has fully processed and confirmed the cancellation. Sometimes there is a delay in receiving the callback from the downstream partner, in which case the token remains in the cancellation_initiated state. You can retry cancelling a token that is in the cancellation_initiated state. If a customer cancels the token directly from their UPI app, you receive this webhook. Ensure your system handles this event to stop any further debit attempts against this token.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "token.cancelled",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_FVIP5DVexjoZjF",
        "entity": "token",
        "token": "5ESJrtR1V6k6mp",
        "bank": null,
        "wallet": null,
        "method": "upi",
        "vpa": {
          "username": "56546",
          "handle": "upi",
          "name": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "cancelled",
          "failure_reason": null
        },
        "auth_type": null,
        "mrn": null,
        "used_at": 1598424055,
        "created_at": 1598424055,
        "start_time": 1598510437,
        "dcc_enabled": false,
        "max_amount": 5600,
        "expired_at": 1913956837
      }
    }
  },
  "created_at": 1599065559
}

Token Paused

Indicates the token has been paused by the customer from their UPI app. No subsequent debits can be executed while the token is in the paused state. The customer can resume or cancel a paused token. When this happens, you receive the token.confirmed or token.cancelled webhook respectively. Sometimes customers pause a token until a certain date. When that date passes, the token moves back to the confirmed state, and the token.confirmed webhook is sent to you as well.

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "token.paused",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_FVIP5DVexjoZjF",
        "entity": "token",
        "token": "5ESJrtR1V6k6mp",
        "bank": null,
        "wallet": null,
        "method": "upi",
        "vpa": {
          "username": "56546",
          "handle": "upi",
          "name": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "paused",
          "failure_reason": null
        },
        "auth_type": null,
        "mrn": null,
        "used_at": 1598424055,
        "created_at": 1598424055,
        "start_time": 1598510437,
        "dcc_enabled": false,
        "max_amount": 5600,
        "expired_at": 1913956837
      }
    }
  },
  "created_at": 1599065559
}

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "token.paused",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_KaQbMNOeH67CZj",
        "entity": "token",
        "token": "SampleTokenValue",
        "bank": null,
        "wallet": null,
        "method": "card",
        "card": {
          "entity": "card",
          "name": "",
          "iin": "999999",
          "last4": "3182",
          "network": "Visa",
          "type": "debit",
          "issuer": "ICIC",
          "international": false,
          "emi": true,
          "sub_type": "consumer",
          "token_iin": "*******",
          "expiry_month": "01",
          "expiry_year": "2099",
          "flows": {
            "otp": true,
            "recurring": true
          },
          "cobranding_partner": null
        },
        "recurring": true,
        "recurring_details": {
          "status": "paused",
          "failure_reason": null
        },
        "auth_type": null,
        "mrn": null,
        "used_at": 1787405269,
        "created_at": 1787405269,
        "expired_at": 1956508199,
        "status": "active",
        "notes": {},
        "error_description": null,
        "source": "business",
        "entity_id": null,
        "dcc_enabled": false,
        "max_amount": 149900,
        "error_code": null,
        "compliant_with_tokenisation_guidelines": true
      }
    }
  },
  "created_at": 1792114532
}

Check Payment Status using Webhooks

You can use these webhooks to check the status of the authorisation payment and subsequent payments.

Webhook Event	Description
`payment.authorized`	Indicates the payment has been authorised. A payment is authorised when the customer’s payment details are successfully authenticated by the bank.
`payment.captured`	Indicates the payment has been captured.
`order.paid`	Indicates the customer has successfully made the payment.
`payment.failed`	Indicates the payment has failed. If the authorisation payment fails, you need to initiate the mandate registration again.

Payment Authorised

Indicates that the payment has been authorised. A payment is authorised when the customer’s payment details are successfully authenticated by the bank. Use this webhook to fetch the token_id from the payment entity and store it for subsequent debits.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "payment.authorized",
  "contains": [
    "payment"
  ],
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_FHhm0UWoNrZT3h",
        "entity": "payment",
        "amount": 100,
        "currency": "INR",
        "status": "authorized",
        "order_id": "order_FHhlVrVCPWGSDC",
        "invoice_id": null,
        "international": false,
        "method": "upi",
        "amount_refunded": 0,
        "refund_status": null,
        "captured": false,
        "description": null,
        "card_id": null,
        "bank": null,
        "wallet": null,
        "vpa": "gaurav.kumar@upi",
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "token_id": "token_FHhm0XTtJg9zqb",
        "notes": {
          "note_key 1": "Beam me up Scotty",
          "note_key 2": "Tea. Earl Gray. Hot."
        },
        "fee": null,
        "tax": null,
        "error_code": null,
        "error_description": null,
        "error_source": null,
        "error_step": null,
        "error_reason": null,
        "acquirer_data": {
          "rrn": "688684363734",
          "upi_transaction_id": "B832E94839C6C5194D2DB36F865F564D"
        },
        "created_at": 1595456636
      }
    }
  },
  "created_at": 1595456636
}

Payment Captured

Indicates that the payment has been captured. For a mandate registration, a payment.captured event means that the first debit was successful. Along with the token.confirmed webhook, it means that the UPI Autopay token for the customer is now active.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "payment.captured",
  "contains": [
    "payment"
  ],
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_FHhm0UWoNrZT3h",
        "entity": "payment",
        "amount": 100,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_FHhlVrVCPWGSDC",
        "invoice_id": null,
        "international": false,
        "method": "upi",
        "amount_refunded": 0,
        "refund_status": null,
        "captured": true,
        "description": null,
        "card_id": null,
        "bank": null,
        "wallet": null,
        "vpa": "gaurav.kumar@upi",
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "token_id": "token_FHhm0XTtJg9zqb",
        "notes": {
          "note_key 1": "Beam me up Scotty",
          "note_key 2": "Tea. Earl Gray. Hot."
        },
        "fee": 0,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "error_source": null,
        "error_step": null,
        "error_reason": null,
        "acquirer_data": {
          "rrn": "688684363734",
          "upi_transaction_id": "B832E94839C6C5194D2DB36F865F564D"
        },
        "created_at": 1595456636
      }
    }
  },
  "created_at": 1595456636
}

Order Paid

Indicates that the customer has successfully made the payment. The order entity has no failed webhook, because you can create multiple payments inside the same order_id, which helps track conversion rates. We recommend that you rely on a combination of payment, order and token status webhooks to understand and track conversion rates.

Handy TipsFor UPI, the invoice_id parameter value is null when using the API-based setup. The invoice_id is populated only when a Registration Link is used.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "order.paid",
  "contains": [
    "payment",
    "order"
  ],
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_FHhm0UWoNrZT3h",
        "entity": "payment",
        "amount": 100,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_FHhlVrVCPWGSDC",
        "invoice_id": null,
        "international": false,
        "method": "upi",
        "amount_refunded": 0,
        "refund_status": null,
        "captured": true,
        "description": null,
        "card_id": null,
        "bank": null,
        "wallet": null,
        "vpa": "gaurav.kumar@upi",
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "token_id": "token_FHhm0XTtJg9zqb",
        "notes": {
          "note_key 1": "Beam me up Scotty",
          "note_key 2": "Tea. Earl Gray. Hot."
        },
        "fee": 0,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "error_source": null,
        "error_step": null,
        "error_reason": null,
        "acquirer_data": {
          "rrn": "688684363734",
          "upi_transaction_id": "B832E94839C6C5194D2DB36F865F564D"
        },
        "created_at": 1595456636
      }
    },
    "order": {
      "entity": {
        "id": "order_FHhlVrVCPWGSDC",
        "entity": "order",
        "amount": 100,
        "amount_paid": 100,
        "amount_due": 0,
        "currency": "INR",
        "receipt": "Receipt No. 1",
        "offer_id": null,
        "status": "paid",
        "attempts": 2,
        "notes": {
          "notes_key_1": "Tea, Earl Grey, Hot",
          "notes_key_2": "Tea, Earl Grey… decaf."
        },
        "created_at": 1595456608
      }
    }
  },
  "created_at": 1595456636
}

Payment Failed

Indicates that the payment has failed. If the authorisation payment fails, you need to initiate the mandate registration again. For subsequent payments, you can retry the debit after checking the failure reason.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "payment.failed",
  "contains": [
    "payment"
  ],
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_EhSxIRyTtshjQr",
        "entity": "payment",
        "amount": 0,
        "currency": "INR",
        "status": "failed",
        "order_id": "order_EhSwt4nx32X1Ss",
        "invoice_id": "inv_EhSwt4FKpTKrdf",
        "international": false,
        "method": "upi",
        "amount_refunded": 0,
        "refund_status": null,
        "captured": false,
        "description": "Invoice #inv_EhSwt4FKpTKrdf",
        "card_id": null,
        "bank": "HDFC",
        "wallet": null,
        "vpa": "gaurav.kumar@okhdfc",
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "token_id": "token_EhSxIV7p0l7yri",
        "notes": {
          "notes_key_1":"Tea, Earl Grey, Hot",
          "notes_key_2":"Tea, Earl Grey… decaf."
        },
        "fee": null,
        "tax": null,
        "error_code": "BAD_REQUEST_ERROR",
        "error_description": "Payment failed",
        "created_at": 1587544209
      }
    }
  },
  "created_at": 1587544212
}

Check Registration Link Status using Webhooks

You can use these webhooks to check the status of the registration link. These are relevant only if you are using the Registration Link flow to initiate mandate registration.

Webhook Event	Description
`invoice.paid`	Indicates that a registration link is successfully paid.
`invoice.expired`	Indicates that a registration link has expired.

Invoice Paid

Indicates that a registration link has been successfully paid.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "invoice.paid",
  "contains": [
    "payment",
    "order",
    "invoice"
  ],
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_FHhw4RhnuZPiuO",
        "entity": "payment",
        "amount": 100,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_FHhvTLKwXS9bnS",
        "invoice_id": "inv_FHhvTPure2cEqZ",
        "international": false,
        "method": "upi",
        "amount_refunded": 0,
        "refund_status": null,
        "captured": true,
        "description": "Invoice #inv_FHhvTPure2cEqZ",
        "card_id": null,
        "bank": null,
        "wallet": null,
        "vpa": "gaurav.kumar@upi",
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "token_id": "token_FHhw4Ufvv7kv9u",
        "notes": {
          "Internal Note": "Random Description"
        },
        "fee": 0,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "error_source": null,
        "error_step": null,
        "error_reason": null,
        "acquirer_data": {
          "rrn": "237153511656",
          "upi_transaction_id": "B1D63A7B0366274F83AF9B3A0D7C5CA8"
        },
        "created_at": 1595457208
      }
    },
    "order": {
      "entity": {
        "id": "order_FHhvTLKwXS9bnS",
        "entity": "order",
        "amount": 100,
        "amount_paid": 100,
        "amount_due": 0,
        "currency": "INR",
        "receipt": null,
        "offer_id": null,
        "offers": {
          "entity": "collection",
          "count": 0,
          "items": []
        },
        "status": "paid",
        "attempts": 3,
        "notes": [],
        "created_at": 1595457173,
        "token": {
          "method": "upi",
          "notes": {
            "Internal Note": "Random Description"
          },
          "recurring_status": null,
          "failure_reason": null,
          "currency": "INR",
          "max_amount": 200000,
          "auth_type": null,
          "expire_at": 1609439399,
          "first_payment_amount": 0
        }
      }
    },
    "invoice": {
      "entity": {
        "id": "inv_FHhvTPure2cEqZ",
        "entity": "invoice",
        "receipt": "Receipt No. 1",
        "invoice_number": "Receipt No. 1",
        "customer_id": "cust_DtHaBuooGHTuyZ",
        "customer_details": {
          "id": "cust_DtHaBuooGHTuyZ",
          "name": "Gaurav Kumar",
          "email": "gaurav.kumar@example.com",
          "contact": "9876543210",
          "gstin": null,
          "billing_address": null,
          "shipping_address": null,
          "customer_name": "Gaurav Kumar",
          "customer_email": "gaurav.kumar@example.com",
          "customer_contact": "9876543210"
        },
        "order_id": "order_FHhvTLKwXS9bnS",
        "payment_id": "pay_FHhw4RhnuZPiuO",
        "status": "paid",
        "expire_by": 1596220199,
        "issued_at": 1595457174,
        "paid_at": 1595457208,
        "cancelled_at": null,
        "expired_at": null,
        "sms_status": "sent",
        "email_status": "sent",
        "date": 1595457173,
        "terms": null,
        "partial_payment": false,
        "gross_amount": 100,
        "tax_amount": 0,
        "taxable_amount": 0,
        "amount": 100,
        "amount_paid": 100,
        "amount_due": 0,
        "first_payment_min_amount": null,
        "currency": "INR",
        "currency_symbol": "₹",
        "description": "Authorization transaction",
        "notes": {
          "Internal Note": "Random Description"
        },
        "comment": null,
        "short_url": "https://rzp.io/i/GZlLJ0d",
        "view_less": true,
        "billing_start": null,
        "billing_end": null,
        "type": "link",
        "group_taxes_discounts": false,
        "supply_state_code": null,
        "user_id": "CTlk1QZN33LQUT",
        "created_at": 1595457174,
        "idempotency_key": null
      }
    }
  },
  "created_at": 1595457208
}

Check Notification Status using Webhooks

You can use these webhooks to check the status of the pre-debit notification sent to the customer. These notification webhooks are currently available only for the decoupled flow, where you send the notification object while creating an order for a subsequent payment. Support for coupled flow is coming soon.

Webhook Event	Description
`notification.delivered`	Indicates that a pre-debit notification is successfully delivered.
`notification.failed`	Indicates that a pre-debit notification has failed to deliver.

Notification Delivered

Indicates that a pre-debit notification is successfully delivered.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "order.notification.delivered",
  "contains": [
    "notification"
  ],
  "payload": {
    "notification": {
      "entity": {
        "id": "notification_00000000000001",
        "entity": "notification",
        "order_id": "order_1Aa00000000002",
        "token_id": "token_M7K2eFBU7vToaQ",
        "delivered_at": 1634057113,
        "status": "delivered",
        "payment_after": 1634057114
      }
    },
    "created_at": 1595456636
  }
}

Notification Failed

Indicates that a pre-debit notification has failed to deliver. You should re-trigger the pre-debit notification before making a debit attempt in these cases.

UPI

{
  "entity": "event",
  "account_id": "acc_8TgNt9DVrJB0bl",
  "event": "order.notification.failed",
  "contains": [
    "notification"
  ],
  "payload": {
    "notification": {
      "entity": {
        "id": "notification_00000000000002",
        "entity": "notification",
        "order_id": "order_1Aa00000000002",
        "token_id": "token_M7K2eFBU7vToaQ",
        "delivered_at": null,
        "status": "failed",
        "payment_after": 1634057114
      }
    },
    "created_at": 1595456636
  }
}

Features

JSON

Check Token Status using Webhooks

Token Confirmed

Token Rejected

Token Cancelled

Token Paused

Check Payment Status using Webhooks

Payment Authorised

Payment Captured

Order Paid

Payment Failed

Check Registration Link Status using Webhooks

Invoice Paid

Check Notification Status using Webhooks

Notification Delivered

Notification Failed

​Check Token Status using Webhooks

​Token Confirmed

​Token Rejected

​Token Cancelled

​Token Paused

​Check Payment Status using Webhooks

​Payment Authorised

​Payment Captured

​Order Paid

​Payment Failed

​Check Registration Link Status using Webhooks

​Invoice Paid

​Check Notification Status using Webhooks

​Notification Delivered

​Notification Failed

Check Token Status using Webhooks

Token Confirmed

Token Rejected

Token Cancelled

Token Paused

Check Payment Status using Webhooks

Payment Authorised

Payment Captured

Order Paid

Payment Failed

Check Registration Link Status using Webhooks

Invoice Paid

Check Notification Status using Webhooks

Notification Delivered

Notification Failed