Instrument Webhook
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 about 1 year ago