4. Webhooks
Set up webhook listeners to receive real-time notifications for UPI Autopay mandate and payment events.
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.
To configure webhooks, go to the
and set up the webhook URL for your account. Know more about .Implementation Considerations
Webhooks are the primary and most efficient method for event notifications. They are delivered asynchronously in near real-time. For critical user-facing flows that need instant confirmation, supplement webhooks with API verification.
Recommended approach
- Rely on webhooks for all automation, which can be asynchronous.
- 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 (, and ) to verify the status.
You can use the below webhooks to check the status of the token (mandate).
Indicates that the bank has completed the mandate registration. Once confirmed, you can execute subsequent payments as per your business needs.
{"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}
Triggered during the mandate registration process, when the registration fails without completion.
{"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}
Triggered when a token is explicitly cancelled or deactivated. This can happen when the customer cancels the mandate from their UPI app or when the merchant cancels it via the
.Handy Tips
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.
Watch Out!
If a customer cancels the mandate directly from their UPI app, you will receive this webhook. Ensure your system handles this event to stop any further debit attempts against this token.
{"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}
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.
Handy Tips
The token.paused event is available only for tokens authorised via UPI. Tokens authorised via Emandate, Card or Paper NACH do not support the paused state.
{"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}
You can use these webhooks to check the status of the authorisation payment and subsequent payments.
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.
{"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}
Indicates that the payment has been captured.
{"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}
Indicates that the customer has successfully made the payment.
Handy Tips
For 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.
{"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}
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.
{"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}
You can use these webhooks to check the status of the registration link. These are relevant only if you are using the
flow to initiate mandate registration.Indicates that a registration link has been successfully paid.
{"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}
You can use these webhooks to check the status of the pre-debit notification sent to the customer. These notification webhooks are available only if you send the notification object while creating an order for a subsequent payment.
Indicates that a pre-debit notification is successfully delivered.
{"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}}
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.
{"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}}
Is this integration guide useful?
ON THIS PAGE