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_typestringIndicates the type of event that triggered the webhook. Possible values: CARD_TRANSACTION_SUCCESS, CARD_TRANSACTION_FAILED, CARD_TRANSACTION_REVERSED, CARD_TRANSACTION_REJECTED. event_timestringThe UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). versionstringThe version of the webhook payload. dataobjectContains 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.
{ "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 } } }
{ "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_idstringMerchant’s unique ID for the user. wallet_idstringMerchant’s unique ID for the wallet. cf_wallet_idstringCashfree’s unique ID for the wallet. card_idstringMerchant’s unique ID for the card. cf_card_idstringCashfree’s unique ID for the card. cf_card_transaction_idstringCashfree’s unique ID for the transaction. amountnumberTransaction amount. channelstringChannel used for transaction (for example, ECOM, POS, ATM). statusstringStatus of the transaction. statusCodestringGranular Status code of the transaction. bank_reference_numberstringBank reference number (RRN) for the transaction. usedAtstringLocation or merchant information where the card was used. initiated_atstringTimestamp when the transaction was initiated (ISO 8601). processed_atstringTimestamp when the transaction was processed (ISO 8601). sub_walletobjectDetails 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_typestringIndicates the type of event that triggered the webhook. Possible values: CARD_REFUND_SUCCESS, CARD_REFUND_FAILED, CARD_REFUND_REJECTED. event_timestringThe UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). versionstringThe version of the webhook payload. dataobjectContains 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.
{ "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 } } }
{ "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 } } }
{ "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_idstringMerchant’s unique ID for the user. wallet_idstringMerchant’s unique ID for the wallet. cf_wallet_idstringCashfree’s unique ID for the wallet. card_idstringMerchant’s unique ID for the card. cf_card_idstringCashfree’s unique ID for the card. cf_card_transaction_idstringCashfree’s unique ID for the original card transaction. cf_card_refund_idstringCashfree’s unique ID for the refund. amountnumberRefund amount. statusstringStatus of the refund. bank_reference_numberstringBank reference number (RRN) for the refund transaction. used_atstringLocation or merchant information where the card was used. initiated_atstringTimestamp when the refund was initiated (ISO 8601). processed_atstringTimestamp when the refund was processed (ISO 8601). sub_walletobjectDetails 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_typestringIndicates the type of event that triggered the webhook. Possible values: PPI_CARD_INACTIVE, PPI_CARD_EXPIRED. event_timestringThe UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). versionstringThe version of the webhook payload. dataobjectContains 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.
{ "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" } } }
{ "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_idstringMerchant’s unique ID for the user. cf_program_idstringCashfree’s unique ID for the card wallet program. wallet_idstringMerchant’s unique ID for the wallet. cf_wallet_idstringCashfree’s unique ID for the wallet. wallet_namestringName of the wallet. sub_walletsarrayList of sub-wallets associated with the wallet. sub_wallets[].cf_sub_wallet_idstringCashfree’s unique ID for the sub-wallet. sub_wallets[].namestringName of the sub-wallet. sub_wallets[].typestringType of the sub-wallet. sub_wallets[].statusstringCurrent status of the sub-wallet. sub_wallets[].balancenumberTotal balance in the sub-wallet. sub_wallets[].available_balancenumberBalance available for transactions in the sub-wallet. sub_wallets[].funds_on_holdnumberFunds that are reserved and not yet available for use. cardobjectDetails of the card whose status was updated. card.card_namestringName of the card program. card.card_idstringMerchant’s unique ID for the card. card.cf_card_idstringCashfree’s unique ID for the card. card.masked_card_numberstringMasked card number. card.name_on_cardstringName as printed on the card. card.card_holder_namestringName of the person holding the card. card.networkstringCard network (for example, RUPAY). card.statusstringNew status of the card (for example, INACTIVE, EXPIRED).
Verifying the signature is mandatory before processing any response. Refer to Signature Verification for more details. 
