Cashfree Payments Developer Documentation

Webhook essential guides

For seamless integration and security in handling your transactions, refer to the following essential guidelines:

Add a webhook
Webhook retries
IPs to whitelist

Add a webhook

Follow the instructions below to configure webhooks for version 2 APIs:

Log in to the Payouts dashboard using your credentials.
Navigate to Developers > Webhooks.
Click Add Webhook URL in the Webhooks page.

In the Add Webhook popup, enter the following information:
- Webhook URL - Enter the URL where you want to receive the transfer related notifications.
- Select a webhook version - Select V2 from the dropdown menu.

Webhook Version: V2
You will receive V2 webhooks only if you select the option as described and configure the respective URL.

Click Test & Add Webhook.

Webhook signature verification code

These code snippets provide functionality to verify the authenticity of webhook requests and to parse the payload data. It ensures that incoming webhook requests are from a trusted source by checking their signature and then processes the request data.

type PayoutWebhookEvent struct {
Type   string
Raw    string
Object interface{}
}

func PayoutVerifyWebhookSignature(signature string, rawBody string, timestamp string) (*PayoutWebhookEvent, error) {
signatureString := timestamp + rawBody
hmacInstance := hmac.New(sha256.New, []byte(*XClientSecret))
hmacInstance.Write([]byte(signatureString))
bytesData := hmacInstance.Sum(nil)
generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
if generatedSignature == signature {
var object interface{}
err := json.Unmarshal([]byte(rawBody), &object)
if err != nil {
return nil, errors.New("something went wrong when unmarshalling raw body")
}
if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
if webhookType, ok := objectAsMapInterface["type"].(string); ok {
return &PayoutWebhookEvent{Type: webhookType, Raw: rawBody, Object: object}, nil
}
}
return &PayoutWebhookEvent{Type: "", Raw: rawBody, Object: object}, nil
}
return nil, errors.New("generated signature and received signature did not match")
}

Components

PayoutWebhookEvent This represents the structure of a webhook event:

Field	Description
Type	It is the type of the event.
Raw	The raw JSON body of the webhook request.
Object	The parsed JSON object from the raw body

PayoutVerifyWebhookSignature This function is used to verify the signature of a webhook request and parse the data. The parameters are as follows:

Field	Description
signature	The HMAC signature provided in the header information of the webhook.
rawBody	The raw JSON body of the request in the string form.
timestamp	The timestamp provided in the header information of the webhook.

Cashfree Class This class provides the method for verifying webhook signatures:

Field	Description
XClientSecret	Secret key
XAPIVersion	It is the API version: 2024-01-01

Webhook events

Payouts webhooks enable you to receive updates about all event-driven activities originating from your account. Below is the list of payouts webhooks:

Events	Notifications
TRANSFER_ACKNOWLEDGED	You will receive this event when the transfer is successful and the amount is debited from the account.
TRANSFER_SUCCESS	You will receive this event when the transferred amount is deposited into the beneficiary bank account.
TRANSFER_FAILED	You will receive this event when the transfer attempt is a failure.
TRANSFER_REVERSED	You will receive this event when the beneficiary bank reversed the transfer request.
TRANSFER_REJECTED	You will receive this event when Cashfree Payments rejected the transfer request.
BULK_TRANSFER_REJECTED	You will receive this event when one of the transfers or all the transfers in the batch transfer request is rejected.

Sample payload

{
	"data": {
		"transfer_id": "JUNOB2018",
		"cf_transfer_id": "123456",
		"status": "SUCCESS",
		"status_code": "COMPLETED",
		"status_description": "The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary.",
		"beneficiary_details": {
			"beneficiary_id": "JOHN18011",
			"beneficiary_instrument_details": {
				"bank_account_number": "7766671501729",
				"bank_ifsc": "SBIN0000003"
			}
		},
		"transfer_amount": 1,
		"transfer_service_charge": 1,
		"transfer_service_tax": 0.18,
		"transfer_mode": "BANK",
		"transfer_utr": "TESTR92023012200543116",
		"fundsource_id": "CASHFREE_1",
		"added_on": "2021-11-24T13:39:25Z",
		"updated_on": "2021-11-24T13:40:27Z"
	},
	"event_time": "2024-07-25T17:43:37",
	"type": "TRANSFER_ACKNOWLEDGED"
}

Parameters

Find the parameters and their description for the events TRANSFER_SUCCESS, TRANSFER_FAILED, TRANSFER_REVERSED, and TRANSFER_REJECTED below:

Parameter	description
transfer_id	It displays the unique ID you created to identify the transfer request.
cf_transfer_id	It displays the unique ID created by Cashfree Payments for reference purpose.
status	It displays the status of the transfer.
status_code	It displays the specific status of the transfer.
status_description	It displays the detailed explanation of the transfer status.
beneficiary_details	It contains information about the beneficiary.
beneficiary_id	It displays the unique ID to identify the beneficiary.
beneficiary_instrument_details	It contains the account information of the beneficiary.
bank_account_number	It displays the bank account number of the beneficiary.
bank_ifsc	It displays the IFSC information of the bank.
transfer_amount	It displays the transfer amount.
transfer_service_charge	It displays the service charge applied for the transfer amount.
transfer_service_tax	It displays the taxable amount for the service charge.
transfer_mode	It displays the transfer mode.
transfer_utr	It displays the unique transaction reference number.
fundsource_id	It displays the unique ID to identify the fund source.
added_on	It displays the date and time of the addition.
updated_on	It displays the date and time of the updation.
event_time	It displays the date and time of the webhook event initiation.
type	It displays the event type.

Find the parameters and their description for the event BULK_TRANSFER_REJECTED below:

Parameter	Description
batch_transfer_id	It displays the unique ID you created to identify the batch transfer request.
cf_batch_transfer_id	It displays the unique ID created by Cashfree Payments for reference purpose.
status	It displays the status of the batch transfer request.
event_time	It displays the date and time of the webhook event initiation.
type	It displays the event type.

Note: A transfer is considered successful only when both the status is ‘SUCCESS’ and the status code is ‘COMPLETED’.

Webhook retries

Cashfree Payments webhooks service does its best to deliver events to your webhook endpoint. It is best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process. Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body gets ignored. Any response code outside the 200 range, including 3xx codes, indicates that you did not receive the webhook. When Cashfree Payments does not get the acknowledgement due to any reason, we retry to establish the communication at regular intervals. If we do not receive the response after few attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times. If do not receive notifications from Cashfree Payments as expected, please fill out the Support Form.

IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree:

UAT
52.66.25.127
15.206.45.168

Prod
52.66.101.190
3.109.102.144
3.111.60.173
18.60.134.245
18.60.183.142

Port
443 (secured)

FAQs

Can I subscribe to webhooks V2 if I use Payout APIs as V1 and V1.2?
Yes, you can subscribe to Webhooks V2 even if you’re currently using Payout APIs v1 and v1.2.
Can I utilise webhooks V1 while using Payouts APIs V2?
Yes, you can typically subscribe to Webhooks V1 even if you’re using Payout APIs V2.
Are the webhook events CREDIT_CONFIRMATION, BENEFICIARY_INCIDENT, and LOW_BALANCE_ALERT, previously available in webhooks V1, still supported and deliverable in Webhooks V2?
Yes, you can continue to receive the CREDIT_CONFIRMATION, BENEFICIARY_INCIDENT, and LOW_BALANCE_ALERT webhook events even after subscribing to Webhooks V2.

Payout APIs

V2

V1

One Escrow

Cashgram

Webhooks Version V2

Webhook essential guides

Add a webhook

Webhook signature verification code

Components

Webhook events

Sample payload

Parameters

Webhook retries

IPs to whitelist

FAQs

Payout APIs

V2

V1

One Escrow

Cashgram

​Webhook essential guides

​Add a webhook

​Webhook signature verification code

​Components

​Webhook events

​Sample payload

​Parameters

​Webhook retries

​IPs to whitelist

​FAQs

Webhook essential guides

Add a webhook

Webhook signature verification code

Components

Webhook events

Sample payload

Parameters

Webhook retries

IPs to whitelist

FAQs