> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Webhooks

> Configure Cashfree Card webhooks to receive event-based notifications whenever card transactions, refunds or card status updates occur in your PPI integration.

Webhooks are event-based notifications that are received when a specific event related to the Card occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.

| Header name         |                 Header value                 |
| ------------------- | :------------------------------------------: |
| content-length      |                     1099                     |
| x-webhook-attempt   |                       1                      |
| content-type        |               application/json               |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp |                 1746427759733                |
| x-webhook-version   |                  2025-01-01                  |

<Tip>
  Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.
</Tip>

## Card transaction webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field        | Type     | Description                                                                                                                                                                               |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `CARD_TRANSACTION_SUCCESS`, `CARD_TRANSACTION_FAILED`, `CARD_TRANSACTION_REVERSED`, `CARD_TRANSACTION_REJECTED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).                                                                                             |
| `version`    | `string` | The version of the webhook payload.                                                                                                                                                       |
| `data`       | `object` | Contains event-specific details related to this feature.                                                                                                                                  |

The following events are triggered at different stages of a card transaction:

| Event                       | Description                                                                    |
| :-------------------------- | :----------------------------------------------------------------------------- |
| CARD\_TRANSACTION\_SUCCESS  | The card transaction was successfully processed.                               |
| CARD\_TRANSACTION\_FAILED   | The card transaction failed due to an error (for example, insufficient funds). |
| CARD\_TRANSACTION\_REVERSED | The card transaction was reversed (for example, a refund or void).             |
| CARD\_TRANSACTION\_REJECTED | The card transaction was rejected by the system or issuer.                     |

<AccordionGroup>
  <Accordion title="CARD_TRANSACTION_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_SUCCESS",
      "event_time": "2025-01-02T15:04:05Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "ECOM",
        "status": "SUCCESS",
        "statusCode": "SUCCESS",
        "bank_reference_number": "123456789012",
        "usedAt": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:04:05Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_FAILED",
      "event_time": "2025-01-02T15:01:30Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 100000.0,
        "channel": "ECOM",
        "status": "FAILED",
        "statusCode": "UNKNOWN_REASON",
        "bank_reference_number": null,
        "usedAt": "LUXURY STORE",
        "initiated_at": "2025-01-02T15:01:00Z",
        "processed_at": "2025-01-02T15:01:30Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_REVERSED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_REVERSED",
      "event_time": "2025-01-02T16:00:00Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "ECOM",
        "status": "REVERSED",
        "statusCode": "REVERSED",
        "bank_reference_number": "123456789012",
        "usedAt": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T16:00:00Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1500.0,
          "available_balance": 1500.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_REJECTED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_REJECTED",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "POS",
        "status": "REJECTED",
        "statusCode": "INSUFFICIENT_BALANCE",
        "bank_reference_number": null,
        "usedAt": "SUSPICIOUS MERCHANT",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:00:01Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card transaction data fields

| Field                    | Type     | Description                                                 |
| ------------------------ | -------- | ----------------------------------------------------------- |
| `user_id`                | `string` | Merchant's unique ID for the user.                          |
| `wallet_id`              | `string` | Merchant's unique ID for the wallet.                        |
| `cf_wallet_id`           | `string` | Cashfree's unique ID for the wallet.                        |
| `card_id`                | `string` | Merchant's unique ID for the card.                          |
| `cf_card_id`             | `string` | Cashfree's unique ID for the card.                          |
| `cf_card_transaction_id` | `string` | Cashfree's unique ID for the transaction.                   |
| `amount`                 | `number` | Transaction amount.                                         |
| `channel`                | `string` | Channel used for transaction (for example, ECOM, POS, ATM). |
| `status`                 | `string` | Status of the transaction.                                  |
| `statusCode`             | `string` | Granular Status code of the transaction.                    |
| `bank_reference_number`  | `string` | Bank reference number (RRN) for the transaction.            |
| `usedAt`                 | `string` | Location or merchant information where the card was used.   |
| `initiated_at`           | `string` | Timestamp when the transaction was initiated (ISO 8601).    |
| `processed_at`           | `string` | Timestamp when the transaction was processed (ISO 8601).    |
| `sub_wallet`             | `object` | Details of the sub-wallet used for the transaction.         |

### Status and statusCode mapping

The following table shows the possible `statusCode` values for each transaction `status`:

| Status   | StatusCode                                                                                                                                                                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RECEIVED | RECEIVED                                                                                                                                                                                                                                          |
| SUCCESS  | SUCCESS                                                                                                                                                                                                                                           |
| REVERSED | REVERSED                                                                                                                                                                                                                                          |
| FAILED   | UNKNOWN\_REASON                                                                                                                                                                                                                                   |
| REJECTED | CARD\_VELOCITY\_LIMIT\_EXCEEDED, INVALID\_CARD, INVALID\_CVV, FRM\_DECLINE, INVALID\_OTP, INSUFFICIENT\_BALANCE, WALLET\_VELOCITY\_LIMIT\_EXCEEDED, USER\_NOT\_ACTIVE, CARD\_NOT\_ACTIVE, CARD\_EXPIRED, MCC\_NOT\_ALLOWED, CHANNEL\_NOT\_ALLOWED |

## Card refund webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field        | Type     | Description                                                                                                                                   |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `CARD_REFUND_SUCCESS`, `CARD_REFUND_FAILED`, `CARD_REFUND_REJECTED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).                                                 |
| `version`    | `string` | The version of the webhook payload.                                                                                                           |
| `data`       | `object` | Contains event-specific details related to this feature.                                                                                      |

The following events are triggered at different stages of a card refund:

| Event                  | Description                                               |
| :--------------------- | :-------------------------------------------------------- |
| CARD\_REFUND\_SUCCESS  | The card refund was successfully processed and credited.  |
| CARD\_REFUND\_FAILED   | The card refund failed due to an error during processing. |
| CARD\_REFUND\_REJECTED | The card refund was rejected by the system or bank.       |

<AccordionGroup>
  <Accordion title="CARD_REFUND_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_SUCCESS",
      "event_time": "2025-01-02T15:04:05Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654321",
        "amount": 500.0,
        "status": "SUCCESS",
        "bank_reference_number": "123456789012",
        "used_at": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:04:05Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1500.0,
          "available_balance": 1500.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_REFUND_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_FAILED",
      "event_time": "2025-01-02T15:01:30Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654322",
        "amount": 100.0,
        "status": "FAILED",
        "bank_reference_number": null,
        "used_at": "LUXURY STORE",
        "initiated_at": "2025-01-02T15:01:00Z",
        "processed_at": "2025-01-02T15:01:30Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_REFUND_REJECTED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_REJECTED",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654323",
        "amount": 500.0,
        "status": "REJECTED",
        "bank_reference_number": null,
        "used_at": "SUSPICIOUS MERCHANT",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:00:01Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card refund data fields

| Field                    | Type     | Description                                               |
| ------------------------ | -------- | --------------------------------------------------------- |
| `user_id`                | `string` | Merchant's unique ID for the user.                        |
| `wallet_id`              | `string` | Merchant's unique ID for the wallet.                      |
| `cf_wallet_id`           | `string` | Cashfree's unique ID for the wallet.                      |
| `card_id`                | `string` | Merchant's unique ID for the card.                        |
| `cf_card_id`             | `string` | Cashfree's unique ID for the card.                        |
| `cf_card_transaction_id` | `string` | Cashfree's unique ID for the original card transaction.   |
| `cf_card_refund_id`      | `string` | Cashfree's unique ID for the refund.                      |
| `amount`                 | `number` | Refund amount.                                            |
| `status`                 | `string` | Status of the refund.                                     |
| `bank_reference_number`  | `string` | Bank reference number (RRN) for the refund transaction.   |
| `used_at`                | `string` | Location or merchant information where the card was used. |
| `initiated_at`           | `string` | Timestamp when the refund was initiated (ISO 8601).       |
| `processed_at`           | `string` | Timestamp when the refund was processed (ISO 8601).       |
| `sub_wallet`             | `object` | Details of the sub-wallet where the refund was credited.  |

## Card status update webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field        | Type     | Description                                                                                                       |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `PPI_CARD_INACTIVE`, `PPI_CARD_EXPIRED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).                     |
| `version`    | `string` | The version of the webhook payload.                                                                               |
| `data`       | `object` | Contains event-specific details related to this feature.                                                          |

The following events are triggered when a card's status changes:

| Event               | Description                                              |
| :------------------ | :------------------------------------------------------- |
| PPI\_CARD\_INACTIVE | The card status has been updated to INACTIVE.            |
| PPI\_CARD\_EXPIRED  | The card has reached its expiry date and is now EXPIRED. |

<AccordionGroup>
  <Accordion title="PPI_CARD_INACTIVE">
    ```json theme={"dark"}
    {
      "event_type": "PPI_CARD_INACTIVE",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "cf_program_id": "10021",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "wallet_name": "PayNext Vendor Program",
        "sub_wallets": [
          {
            "cf_sub_wallet_id": "35246543210987654321",
            "name": "Holiday Gift Card 2026",
            "type": "STANDARD_PPI",
            "status": "ACTIVE",
            "balance": 0.00,
            "available_balance": 0.00,
            "funds_on_hold": 0.00
          }
        ],
        "card": {
          "card_name": "PayNext Vendor Program",
          "card_id": "CARD5678",
          "cf_card_id": "78901234567890123",
          "masked_card_number": "XXXXXXXXXXXX7092",
          "name_on_card": "John Doe",
          "card_holder_name": "John Doe",
          "network": "RUPAY",
          "status": "INACTIVE"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="PPI_CARD_EXPIRED">
    ```json theme={"dark"}
    {
      "event_type": "PPI_CARD_EXPIRED",
      "event_time": "2025-01-02T00:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "cf_program_id": "10021",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "wallet_name": "PayNext Vendor Program",
        "sub_wallets": [
          {
            "cf_sub_wallet_id": "35246543210987654321",
            "name": "Holiday Gift Card 2026",
            "type": "STANDARD_PPI",
            "status": "ACTIVE",
            "balance": 0.00,
            "available_balance": 0.00,
            "funds_on_hold": 0.00
          }
        ],
        "card": {
          "card_name": "PayNext Vendor Program",
          "card_id": "CARD5678",
          "cf_card_id": "78901234567890123",
          "masked_card_number": "XXXXXXXXXXXX7092",
          "name_on_card": "John Doe",
          "card_holder_name": "John Doe",
          "network": "RUPAY",
          "status": "EXPIRED"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card status update data fields

| Field                             | Type     | Description                                              |
| --------------------------------- | -------- | -------------------------------------------------------- |
| `user_id`                         | `string` | Merchant's unique ID for the user.                       |
| `cf_program_id`                   | `string` | Cashfree's unique ID for the card wallet program.        |
| `wallet_id`                       | `string` | Merchant's unique ID for the wallet.                     |
| `cf_wallet_id`                    | `string` | Cashfree's unique ID for the wallet.                     |
| `wallet_name`                     | `string` | Name of the wallet.                                      |
| `sub_wallets`                     | `array`  | List of sub-wallets associated with the wallet.          |
| `sub_wallets[].cf_sub_wallet_id`  | `string` | Cashfree's unique ID for the sub-wallet.                 |
| `sub_wallets[].name`              | `string` | Name of the sub-wallet.                                  |
| `sub_wallets[].type`              | `string` | Type of the sub-wallet.                                  |
| `sub_wallets[].status`            | `string` | Current status of the sub-wallet.                        |
| `sub_wallets[].balance`           | `number` | Total balance in the sub-wallet.                         |
| `sub_wallets[].available_balance` | `number` | Balance available for transactions in the sub-wallet.    |
| `sub_wallets[].funds_on_hold`     | `number` | Funds that are reserved and not yet available for use.   |
| `card`                            | `object` | Details of the card whose status was updated.            |
| `card.card_name`                  | `string` | Name of the card program.                                |
| `card.card_id`                    | `string` | Merchant's unique ID for the card.                       |
| `card.cf_card_id`                 | `string` | Cashfree's unique ID for the card.                       |
| `card.masked_card_number`         | `string` | Masked card number.                                      |
| `card.name_on_card`               | `string` | Name as printed on the card.                             |
| `card.card_holder_name`           | `string` | Name of the person holding the card.                     |
| `card.network`                    | `string` | Card network (for example, RUPAY).                       |
| `card.status`                     | `string` | New status of the card (for example, INACTIVE, EXPIRED). |

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/api-reference/prepaid-payment-instruments/webhook-signature-verification#webhook-signature-verification) for more details.
</Note>