Skip to main content
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_card has 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

  1. Verify the signature. X-Razorpay-Signature is 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.
  2. Acknowledge fast. Answer with any 2xx within 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.
  3. Expect repeats and any order. Process each X-Razorpay-Event-Id once, and keep the ids you have seen for at least 24 hours. Order events about one instrument by created_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 to needs_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 a one_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 to under_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, and reason says why. Answer it again with POST …/requirements.
account.payment_methods.requirements.updated

Next Step

Cash on Delivery
Last modified on November 20, 2026