Instrument Webhook

Suggest Edits

Instrument webhooks can be configured by merchants to receive asynchronous notifications for every update on the instrument status. Merchants must use the instrument status updates to change the status on their servers because of the actions taken by entities apart from the merchant. For example, if the card instrument is deactivated by the issuing bank, then notification would be sent to Cashfree Payments by the issuing bank via the respective card network. Cashfree Payments would update the instrument status to deactivated but the merchant would not have visibility of the instrument deactivation. In this case, merchants can subscribe to the instrument webhooks to stay updated with the recent instrument status update.

The Instrument webhooks can be configured in such a way that each instrument status update can be consumed on a different URL. For example, for Instrument Active status update and Instrument Deactivated status update merchants can configure different URLs and consume the webhook response. Currently, we support webhook only for instrument active notifications.

The webhook notification will be sent on all the URLs added and enabled under instrument webhook. Merchants can add new URLs and enable or disable existing URLs for instrument webhook at any point in time, and it will reflect instantly.

Click here to know how to configure webhooks.

Sample Payload


{
   "data":{
      "instrument":{
         "customer_id":"siddhesh199721",
         "afa_reference":"887316963",
         "instrument_id":"af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
         "instrument_type":"card",
         "instrument_uid":"680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
         "instrument_display":"XXXXXXXXXXXX6854",
         "instrument_status":"ACTIVE",
         "added_at":"2022-04-14T10:42:59+05:30",
         "instrument_meta":{
            "card_network":"visa",
            "card_bank_name":"HDFC BANK",
            "card_country":"IN",
            "card_type":"credit",
            "card_token_details":null
         }
      }
   },
   "event_time":"2022-04-14T10:44:14+05:30",
   "type":"INSTRUMENT_ACTIVE_WEBHOOK"
}

Payload Field Description

Field	Description	Example
customer_id (String)	The customer ID associated with the save instrument request. It is sent by the merchant as a part of create order request in the customer id field.	user199721
afa_reference (String)	cf_payment_id of the successful transaction done while saving instrument.	887316963
instrument_id (String)	The reference id of the saved instrument. Unique for a save instrument request but not unique for a particular instrument like card number or VPA.	af250dc5-e5e5-4e7d-a7cf-3f446741fa54
instrument_type (String)	Type of instrument - card, vpa	card
instrument_uid (String)	Unique identifier for the instrument. For example, if a same card is saved by 2 different customers the instrument_uid would be same for both the cards.	680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660
instrument_display (String)	The display text for the saved instrument. For example, in case of saved cards the first 12 digits would be masked and only the last 4 digits would be visible in the instrument display string. It can be displayed to the customer for selecting a saved instrument for payment.	XXXXXXXXXXXX6854
instrument_status (String)	The status of saved instrument - INACTIVE, ACTIVE	ACTIVE
added_at (String)	Timestamp at which instrument was saved.	2022-04-14T10:42:59+05:30
card_network (String)	The card network to which the saved card belongs. Visa, Mastercard, Rupay, etc.	visa
card_bank_name (String)	Card issuing bank name.	HDFC BANK
card_country (String)	Card issuing country code.	IN
card_type (String)	debit, credit, prepaid, etc.	debit
card_token_details (Object)	Additional card token details like card token expiry, card token would be passed in this object. Note: Currently, the field is always passed as null.	null
event_time (String)	Time at which webhook was initiated.	2022-02-28T13:04:28+05:30
type (String)	Type of the instrument webhook.	INSTRUMENT_ACTIVE_WEBHOOK

Updated 5 months ago