PPI Card Webhooks | Cashfree Payments

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

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.

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

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.

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.

CARD_TRANSACTION_SUCCESS

{
  "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
    }
  }
}

CARD_TRANSACTION_FAILED

{
  "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
    }
  }
}

CARD_TRANSACTION_REVERSED

{
  "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
    }
  }
}

CARD_TRANSACTION_REJECTED

{
  "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
    }
  }
}

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.

CARD_REFUND_SUCCESS

{
  "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
    }
  }
}

CARD_REFUND_FAILED

{
  "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
    }
  }
}

CARD_REFUND_REJECTED

{
  "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
    }
  }
}

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.

PPI_CARD_INACTIVE

{
  "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"
    }
  }
}

PPI_CARD_EXPIRED

{
  "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"
    }
  }
}

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).

Verifying the signature is mandatory before processing any response. Refer to Signature Verification for more details.

​Webhook signature

​Card transaction webhooks

​Webhook payload fields

​Card transaction data fields

​Status and statusCode mapping

​Card refund webhooks

​Webhook payload fields

​Card refund data fields

​Card status update webhooks

​Webhook payload fields

​Card status update data fields

Webhook signature

Card transaction webhooks

Webhook payload fields

Card transaction data fields

Status and statusCode mapping

Card refund webhooks

Webhook payload fields

Card refund data fields

Card status update webhooks

Webhook payload fields

Card status update data fields