Available in🇮🇳 India
Banks, providers and Razorpay move an instrument through onboarding over days. Razorpay tells your platform when an instrument changes, so you do not have to poll. Events are delivered the same way as the Onboarding APIs webhooks, to the same webhook URL.
Every event carries the current state of one instrument, as the instrument object the fetch response returns. One handler serves every event: verify, drop repeats, replace the instrument you hold and re-render. Fetching its payment method is always the source of truth.
4.1 Subscribe to the Webhook
Subscribe on the Partner Dashboard, once per mode, with an https URL, a secret and the events to receive.4.2 Event Object
4.3 Status Change Event
SBI credit-card EMI is activated by the bank. It was enabled before, so customers can pay with it as soon as it is activated.account.payment_methods.updated
Handy Tips
- Switching an activated instrument on or off changes only
enabled, not its status, so no event fires. - A group such as
debit_cardhas no event of its own. Its status is derived from its members, and the event is sent for the instrument whose status changed. - A requirement that several instruments list produces one event per instrument, each with that instrument’s requirements.
4.4 Handle the Webhook
- Verify the signature.
X-Razorpay-Signatureis the HMAC-SHA256 of the raw body, keyed with your webhook secret, as hex. Read the secret from your environment or secrets manager. Reject an event that does not match. - Acknowledge fast. Answer with any
2xxwithin 5 seconds, then do the work. Razorpay retries anything else with exponential backoff for up to 24 hours. After that, it does not send the event again, so fetch its payment method to catch up. - Expect repeats and any order. Process each
X-Razorpay-Event-Idonce, and keep the ids you have seen for at least 24 hours. Order events about one instrument bycreated_at, and ignore one older than the last you applied for that instrument. Fetch its payment method when in doubt.
4.5 Clarifications in Events
When an instrument moves toneeds_clarification, the event carries the flagged points in the instrument’s requirements: the reviewer’s or the bank’s comment in reason, what to send in description and value_type, and the accepted files or limits in metadata.constraints. Show them to the merchant straight from the event. Fetch only to catch up on a missed event. Events never carry an answer or a file.
You cannot answer by webhook. The reply to an event is only its 2xx acknowledgement, within 5 seconds. The merchant answers with Upload a document and Answer requirements, and an event is sent again when the instrument moves on.
One Document to Send
HDFC Bank asks again for a clear photo of the shop. The merchant uploads a photo and answers with its id.account.payment_methods.updated
One Value to Correct
HDFC Bank finds that the PAN does not match the GST certificate. The merchant sends the right PAN in text.account.payment_methods.updated
A Choice
HDFC Bank needs a refund policy page. This is aone_of composite: the merchant either shares a website that has the page or replies, and answers only the one chosen.
account.payment_methods.updated
A Document and a Reply at Once
ICICI Bank flags two points in one event: a clear cheque and contact details. The requirements answered earlier are no longer listed. Answer both new points together in one call.account.payment_methods.updated
Clarification Answered
After the only flagged point is answered, HDFC debit-card EMI is back tounder_review and its requirements list is empty.
account.payment_methods.updated
An Answer Failed a Later Check
The GSTIN sent earlier fails the check against the GST portal. The instrument’s status does not change, so this is the requirements event. The requirement is back in the list, andreason says why. Answer it again with POST …/requirements.
account.payment_methods.requirements.updated