Use Razorpay Webhooks to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL.

Webhook Events for Token Status Updates

The table below lists the Webhook events available for tokens.

Event	Description
`token.initiated`	Triggered when tokenisation request is initiated.
`token.service_provider_token.activated`	Triggered when, for a given service provider: • The token status is changed to `activated` for the first time. • The token status for a previously suspended token is changed to `activated` again.
`token.service_provider_token.suspended`	Triggered when, for a given service provider, the issuing bank temporarily suspends a token.
`token.service_provider_deactivated`	Triggered when, for a given service provider, the issuing bank permanently deactivates a token.
`token.service_provider_expiry_updated`	Triggered when, for a given service provider, the issuing bank updates the expiry date for a token.

Handy Tips

In case of network tokenised cards, the last 4 digits will be of the tokenised card and not the actual card.

token.initiated

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.initiated",
  "contains": [
    "token"
  ],
  "payload": {
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer",
          "token_iin": "453335"
        },
        "compliant_with_tokenisation_guidelines": true,
        "expired_at": 1748716199,
        "status": "initiated",
        "notes": []
      }
    }
  }
}

token.service_provider_token.activated

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.service_provider_token.activated",
  "contains": [
    "service_provider_token",
    "token"
  ],
  "payload": {
    "service_provider_token": {
      "entity": {
        "id": "spt_1234abcd",
        "entity": "service_provider_token",
        "provider_type": "network",
        "provider_name": "Visa",
        "interoperable": true,
        "status": "activated",
        "provider_data": {
          "token_reference_number": "sas7wqaoidasdfssdjjk",
          "payment_account_reference": "8324ssdas7wqaoidassdjjk",
          "token_iin": "453335",
          "token_expiry_month": 12,
          "token_expiry_year": 2021
        }
      }
    },
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer"
        },
        "compliant_with_tokenisation_guidelines": true,
        "service_provider_tokens": [
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "network",
            "provider_name": "Visa",
            "interoperable": true,
            "status": "activated",
            "provider_data": {
              "token_reference_number": "sas7wqaoidasdfssdjjk",
              "payment_account_reference": "8324ssdas7wqaoidassdjjk",
              "token_iin": "453335",
              "token_expiry_month": 12,
              "token_expiry_year": 2021
            }
          },
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "aggregator",
            "provider_name": "razorpay",
            "interoperable": false,
            "status": "activated",
            "provider_data": {
              "expired_at": 1748716199
            }
          }
        ],
        "expired_at": 1748716199,
        "status": "activated",
        "notes": []
      }
    }
  }
}

Sample Payload for token.service_provider_token.activated as part of payment

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.service_provider_token.activated",
  "contains": [
    "service_provider_token",
    "token"
  ],
  "payload": {
    "service_provider_token": {
      "entity": {
        "id": "spt_1234abcd",
        "entity": "service_provider_token",
        "provider_type": "network",
        "provider_name": "Visa",
        "interoperable": true,
        "status": "activated",
        "provider_data": {
          "token_reference_number": "sas7wqaoidasdfssdjjk",
          "payment_account_reference": "8324ssdas7wqaoidassdjjk",
          "token_iin": "453335",
          "token_expiry_month": 12,
          "token_expiry_year": 2021
        }
      }
    },
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer"
        },
        "compliant_with_tokenisation_guidelines": true,
        "service_provider_tokens": [
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "network",
            "provider_name": "Visa",
            "interoperable": true,
            "status": "activated",
            "provider_data": {
              "token_reference_number": "sas7wqaoidasdfssdjjk",
              "payment_account_reference": "8324ssdas7wqaoidassdjjk",
              "token_iin": "453335",
              "token_expiry_month": 12,
              "token_expiry_year": 2021
            }
          },
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "aggregator",
            "provider_name": "razorpay",
            "interoperable": false,
            "status": "activated",
            "provider_data": {
              "expired_at": 1748716199
            }
          }
        ],
        "expired_at": 1748716199,
        "status": "activated",
        "notes": []
      }
    },
    "payment": {
      "entity": {
        "id": "pay_FPoJKWQQ8lK13n",
        "entity": "payment",
        "amount": 500000,
        "currency": "INR",
        "base_amount": 500000,
        "status": "captured",
        "order_id": "order_FPoIeimWki9j8A",
        "invoice_id": null,
        "international": false,
        "method": "netbanking",
        "amount_refunded": 190000,
        "amount_transferred": 0,
        "refund_status": "partial",
        "captured": true,
        "description": null,
        "card_id": null,
        "bank": "HDFC",
        "wallet": null,
        "vpa": null,
        "email": "gaurav.kumar@example.com",
        "contact": "+919000090000",
        "notes": [],
        "fee": 11800,
        "tax": 1800,
        "error_code": null,
        "error_description": null,
        "error_source": null,
        "error_step": null,
        "error_reason": null,
        "acquirer_data": {
          "bank_transaction_id": "4827433"
        },
        "created_at": 1597226379
      }
    }
  }
}

token.service_provider_token.suspended

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.service_provider_token.suspended",
  "contains": [
    "service_provider_token",
    "token"
  ],
  "payload": {
    "service_provider_token": {
      "entity": {
        "id": "spt_1234abcd",
        "entity": "service_provider_token",
        "provider_type": "network",
        "provider_name": "Visa",
        "interoperable": true,
        "status": "suspended",
        "provider_data": {
          "token_reference_number": "sas7wqaoidasdfssdjjk",
          "payment_account_reference": "8324ssdas7wqaoidassdjjk",
          "token_iin": "453335",
          "token_expiry_month": 12,
          "token_expiry_year": 2021
        }
      }
    },
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer"
        },
        "compliant_with_tokenisation_guidelines": true,
        "service_provider_tokens": [
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "network",
            "provider_name": "Visa",
            "interoperable": true,
            "status": "suspended",
            "provider_data": {
              "token_reference_number": "sas7wqaoidasdfssdjjk",
              "payment_account_reference": "8324ssdas7wqaoidassdjjk",
              "token_iin": "453335",
              "token_expiry_month": 12,
              "token_expiry_year": 2021
            }
          },
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "aggregator",
            "provider_name": "razorpay",
            "interoperable": false,
            "status": "activated",
            "provider_data": {
              "expired_at": 1748716199
            }
          }
        ],
        "expired_at": 1748716199,
        "status": "activated",
        "notes": []
      }
    }
  }
}

token.service_provider_token.deactivated

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.service_provider_token.deactivated",
  "contains": [
    "service_provider_token",
    "token"
  ],
  "payload": {
    "service_provider_token": {
      "entity": {
        "id": "spt_1234abcd",
        "entity": "service_provider_token",
        "provider_type": "network",
        "provider_name": "Visa",
        "interoperable": true,
        "status": "deactivated",
        "provider_data": {
          "token_reference_number": "sas7wqaoidasdfssdjjk",
          "payment_account_reference": "8324ssdas7wqaoidassdjjk",
          "token_iin": "453335",
          "token_expiry_month": 12,
          "token_expiry_year": 2021
        }
      }
    },
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer"
        },
        "compliant_with_tokenisation_guidelines": true,
        "service_provider_tokens": [
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "network",
            "provider_name": "Visa",
            "interoperable": true,
            "status": "deactivated",
            "provider_data": {
              "token_reference_number": "sas7wqaoidasdfssdjjk",
              "payment_account_reference": "8324ssdas7wqaoidassdjjk",
              "token_iin": "453335",
              "token_expiry_month": 12,
              "token_expiry_year": 2021
            }
          }
        ],
        "expired_at": 1748716199,
        "status": "deactivated",
        "notes": []
      }
    }
  }
}

token.service_provider_token.expiry_updated

{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "token.service_provider_token.expiry_updated",
  "contains": [
    "service_provider_token",
    "token"
  ],
  "payload": {
    "service_provider_token": {
      "entity": {
        "id": "spt_1234abcd",
        "entity": "service_provider_token",
        "provider_type": "network",
        "provider_name": "Visa",
        "interoperable": true,
        "status": "activated",
        "provider_data": {
          "token_reference_number": "sas7wqaoidasdfssdjjk",
          "payment_account_reference": "8324ssdas7wqaoidassdjjk",
          "token_iin": "453335",
          "token_expiry_month": 12,
          "token_expiry_year": 2022
        }
      }
    },
    "token": {
      "entity": {
        "id": "token_4lsdksD31GaZ09",
        "entity": "token",
        "customer_id": "cust_1Aa00000000001",
        "method": "card",
        "card": {
          "last4": "3335",
          "network": "Visa",
          "type": "debit",
          "issuer": "HDFC",
          "international": false,
          "emi": true,
          "sub_type": "consumer"
        },
        "compliant_with_tokenisation_guidelines": true,
        "service_provider_tokens": [
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "network",
            "provider_name": "Visa",
            "interoperable": true,
            "status": "activated",
            "provider_data": {
              "token_reference_number": "sas7wqaoidasdfssdjjk",
              "payment_account_reference": "8324ssdas7wqaoidassdjjk",
              "token_iin": "453335",
              "token_expiry_month": 12,
              "token_expiry_year": 2022
            }
          },
          {
            "id": "spt_1234abcd",
            "entity": "service_provider_token",
            "provider_type": "aggregator",
            "provider_name": "razorpay",
            "interoperable": false,
            "status": "activated",
            "provider_data": {
              "expired_at": 1748716199
            }
          }
        ],
        "expired_at": 1748716199,
        "status": "activated",
        "notes": []
      }
    }
  }
}

Tokenisation Webhooks