Wallet Webhooks

Webhooks are server callbacks to your server from Cashfree payments.

Webhooks are event-based notifications that are received when a specific event related to the Wallet 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.

Wallet Credit events

The following are examples of webhook events that you may receive.

PPI_CREDIT_SUCCESS

{
  "event_type": "PPI_CREDIT_SUCCESS",
  "event_time": "2006-01-02T15:04:05Z",
  "data": {
    "credit_id": "CREDIT126345",
    "cf_credit_id": "8901234567890123456",
    "wallet_id": "WALLET936721",
    "user_id": "USER827364",
    "amount": 100.5,
    "sub_wallet": {
      "cf_sub_wallet_id": "35246543210987654321",
      "name": "Gift Wallet",
      "type": "GIFT_PPI",
      "status": "ACTIVE",
      "balance": 1500.75
    },
    "issued_gift_code": {
      "code": "GIFT-2025-XYZ123",
      "value": 100.5,
      "expiry": "2025-12-31T23:59:59Z"
    },
    "status": "SUCCESS",
    "remarks": "Refund for order 123",
    "initiated_at": "2025-09-02T10:15:30Z",
    "processed_at": "2025-09-02T10:20:45Z"
  }
}

Wallet Transfer events

The following are examples of transfer webhook events that you may receive for different transfer statuses.

PPI_TRANSFER_SUCCESS

{
  "event_type": "PPI_TRANSFER_SUCCESS",
  "event_time": "2006-01-02T15:04:05Z",
  "data": {
    "user_id": "USER827364",
    "wallet_id": "WALLET936721",
    "cf_transfer_id": "8901234567890123456",
    "transfer_id": "TRANSFER123456",
    "amount": 500.75,
    "transfer_mode": "NEFT",
    "sub_wallet": {
      "cf_sub_wallet_id": "35246543210987654321",
      "name": "Cashfree payout Wallet",
      "type": "FULL_KYC_PPI",
      "status": "ACTIVE",
      "balance": 8749.55
    },
    "status": "SUCCESS",
    "status_code": "COMPLETED",
    "bank_ref_no": "BNK202502101530001",
    "bene_details": {
      "bene_id": "BENE123",
      "cf_bene_instrument_id": "35246543210987654323",
      "instrument_details": {
        "bank_account_number": "1234567890",
        "ifsc": "HDFC0000123"
      }
    },
    "purpose": "BUSINESS",
    "remarks": "Vendor payment",
    "notes": {
      "example_key": "example_value",
      "example_key2": "example_value2"
    },
    "initiated_at": "2025-09-02T10:15:30Z",
    "processed_at": "2025-09-02T10:17:45Z"
  }
}

Wallet Credit 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.
event_time	string	The UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
data	object	Contains event-specific details related to this feature.

Wallet Transfer webhook payload fields

Transfer webhook events contain additional fields specific to transfer operations:

Field	Type	Description
event_type	string	Type of transfer event: PPI_TRANSFER_SUCCESS, PPI_TRANSFER_FAILED, PPI_TRANSFER_REVERSED, or PPI_TRANSFER_REJECTED
event_time	string	The UTC timestamp when the event occurred, in ISO 8601 format
data	object	Transfer-specific event details
data.user_id	string	Identifier of the user who initiated the transfer
data.wallet_id	string	Identifier of the wallet from which the transfer was made
data.transfer_id	string	Your unique identifier for the transfer transaction
data.cf_transfer_id	string	Cashfree’s unique identifier for the transfer transaction
data.amount	number	Transfer amount
data.transfer_mode	string	Transfer mode used: RTGS, NEFT, IMPS, or UPI
data.sub_wallet	object	Details of the sub-wallet from which funds were transferred
data.status	string	Final status of the transfer: SUCCESS, FAILED, REVERSED, or REJECTED
data.status_code	string	Status code for detailed tracking: COMPLETED, INVALID_ACCOUNT_FAIL, REVERSED, or REJECTED
data.bank_ref_no	string	Bank reference number for the transaction (null if transfer failed before processing)
data.bene_details	object	Beneficiary details including instrument information
data.purpose	string	Purpose of the transfer
data.remarks	string	Additional remarks for the transfer
data.notes	object	Custom key-value pairs provided during transfer creation
data.initiated_at	string	Timestamp when the transfer was initiated
data.processed_at	string	Timestamp when the transfer was completed/failed

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