Partner Webhook Setup | Cashfree Payments

Visit https://partner.cashfree.com login with your partner credentials
On the landing page click on developers section and select webhook, you will be redirected to a page to add webhook URL and subscribe events or once logged in you can use this URL Webhook Page
Add your webhook URL and subscribe events Global Collect Transaction, Global Collect Settlement & Global Collect Virtual Account
To validate the webhook signature follow Adding webhook and signature verification guide

Screenshots:

Landing page to add the webhook URL and subscribe the events

We can add multiple webhook URLs for the different type of events. For testing, Switch to test and follow the same step in sandbox environment.

Transaction status

Active Event needs to be subscribed: Global Collect Transaction

Json

{
	"amount": "4.50",
	"currency": "GBP",
	"cmsProfileId": 123,
	"event": "INTERNATIONAL_PAYMENT_COLLECTED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentTime": "2022-12-29 13:42:54",
	"referenceId": 63,
	"remarks": "",
	"remitterAccount": "1223456789",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TRWIBEB1XXX",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"status": "COMPLETED",
	"utr": "5347f52a-9851-4fe9-8618-32eb085590ce",
	"updatedStatusTime": "2022-12-29 13:50:35",
	"vAccountId": "97836",
	"vAccountNumber": "GB38TCCL12345687997836"
}

Possible events and corresponding transaction status mapping

Event name	Payment status	Description
INTERNATIONAL_PAYMENT_COLLECTED	COMPLETED	Received payment
INTERNATIONAL_PAYMENT_BLOCKED	BLOCKED	The transaction has been blocked due to the specified reason in the designated field.
INTERNATIONAL_PAYMENT_AWAITING_DETAILS	COMPLETED	Waiting for the details of the transaction

Payload field description

Field	Description	Example
amount	The foreign currency amount sent	4.50
currency	Three character ISO code. View list of supported currencies here.	GBP
cmsProfileId	Merchant identifier	123
event	Webhook event	INTERNATIONAL_AMOUNT_COLLECTED
paymentTime	The time at which the payment was initiated.	2022-12-29 13:42:54
referenceId	Cashfree Payments transaction identifier	63
remarks	Remarks passed by the sender.	Sample Remark
reason	Reason regarding the transaction being blocked.	Transaction value below the allowed limit
remitterAccount	The bank account number of the person who sends the money.	1223456789
remitterAddress	The address of the person who sends the money.	Dummy Address
remitterBic	Bank identifier code for the remitter.	TRWIBEB1XXX
remitterCountry	The country from which the money is sent.	GB
remitterName	The name of the remitter who is sending the money.	John Doe
remitterRoutingCode	The routing code of the remitter’s bank.	TLG0123
status	Status of FCY (foreign currency leg) of transaction.	COMPLETED, FAILED, AWAITING_DETAILS
updatedStatusTime	The time of the last status update.	2022-12-29 13:50:35
vAccountId	Identifier of the virtual account.	97836
vAccountNumber	Account number to which the payment was done.	GB38TCCL12345687997836
merchant	Object contains merchant_id used while creating merchant	CF_7644f46b-ad82-472c-8d97-609d1a429eac

Reversal status

JSON

{
  "amount": "1000000.00",
  "cmsProfileId": 123,
  "currency": "USD",
  "event": "INTERNATIONAL_PAYMENT_REVERSAL_INITIATED",
  "merchant": {
    "merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
  },
  "paymentTime": "2024-02-28 16:17:48",
  "referenceId": 63,
  "remitterAccount": "9919391193",
  "remitterAddress": "Dummy Address",
  "remarks": "",
  "remitterBic": "",
  "remitterCountry": "IN",
  "remitterName": "Dummy Sender",
  "remitterRoutingCode": "TLG0123",
  "reversal": {
    "reason": "Transaction value higher than the compliant limit",
    "status": "INITIATED"
  },
  "signature": "F8raBNGcGjMUvbh2t/7t/9C4zU0Snqa/iXf9XzvOq0Y=",
  "status": "REVERSAL_INITIATED",
  "updatedStatusTime": "2024-02-28 16:17:54",
  "utr": "IF-20240228-KT9ZFA",
  "vAccountId": "GB75T",
  "vAccountNumber": "GB75TCCL12345654108280"
}

Possible events and corresponding transaction status mapping

Event name	Reversal status	Transaction status	Description
INTERNATIONAL_PAYMENT_REVERSAL_INITIATED	INITIATED	REVERSAL_INITIATED	Reversal for the transaction is initiated.
INTERNATIONAL_PAYMENT_REVERSAL_DONE	DONE	REVERSAL_DONE	Reversal for the transaction is completed. The funds have been successfully returned to the sender.

Payload field description

Settlement status

Active Event needs to be subscribed: Global Collect Settlement

{
	"amount": "3500.00",
	"cmsProfileId": 23853384,
	"currency": "USD",
	"event": "INR_SETTLEMENT_INITIATED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentRail": "ACH",
	"paymentTime": "2024-02-06 11:11:42",
	"referenceId": 312620,
	"remarks": "EMULATE GC INCOMING FUNDS",
	"remitterAccount": "7337377781",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TLG0123",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"settlement": {
		"expectedSettlementDate": "2024-02-06",
		"fxRate": 85.12,
		"id": "f16581f5-344c-40e8-be4b-e63cb5714a88",
		"inrAmount": 16219.65,
		"netPartnerCommission": 2106.72,
		"settlementCharge": 4213.44,
		"settlementChargeTax": 758.42,
		"status": "INITIATED"
	},
	"status": "READY_FOR_SETTLEMENT",
	"updatedStatusTime": "2024-02-05 18:39:42",
	"utr": "f185d0f5-abf5-492b-9149-d45eacfeaca7",
	"vAccountId": "03314",
	"vAccountNumber": "0331496070"
}

The firaFileDownloadUrl field will only be included in the webhook response after it has been updated.

Possible events and corresponding settlement status mapping

Event name	Settlement status	Description
INR_SETTLEMENT_INITIATED	INITIATED	The settlement is initiated.
INR_SETTLEMENT_APPROVED	SETTLED	The settlement is settled.
INR_SETTLEMENT_REJECTED	REJECTED	The settlement is rejected.
FIRA_FILE_RECEIVED	SETTLED	FIRA file received for the settlement.

Payload field description

Field	Description	Example
amount	The foreign currency amount sent	4.50
currency	Three character ISO code. View list of supported currencies.	GBP
cmsProfileId	Merchant identifier	123
event	Webhook event	INTERNATIONAL_AMOUNT_COLLECTED
merchant	Object contains the merchant_id to map the merchant created.	CF_7644f46b-ad82-472c-8d97-609d1a429eac
paymentTime	The time at which the payment was initiated.	2022-12-29 13:42:54
referenceId	Cashfree Payments transaction identifier	63
remarks	Remarks passed by the sender.	Sample Remark
remitterAccount	The bank account number of the person who sends the money.	1223456789
remitterAddress	The address of the person who sends the money.	Dummy Address
remitterBic	Bank identifier code for the remitter.	TRWIBEB1XXX
remitterCountry	The country from which the money is sent.	GB
remitterName	The name of the remitter who is sending the money.	John Doe
remitterRoutingCode	The routing code of the remitter’s bank.	TLG0123
status	Status of FCY (foreign currency leg) of transaction.	COMPLETED, FAILED
updatedStatusTime	The time of the last status update.	2022-12-29 13:50:35
vAccountId	Identifier of the virtual account.	97836
vAccountNumber	Account number to which the payment was made.	GB38TCCL12345687997836
paymentRail	Payment Network used to make the payment	ACH,EFT,FPS,SEPA,SWIFT,FEDWIRE
settlement.id	Unique reference ID for the settlement since the payment can have multiple settlements.	b84a7c4c-2ce0-48ca-9b86-2a2c9ad5a35d
settlement.fxRate	The foreign exchange rate used for currency conversion between the transaction currency and settlement currency	85.12
settlement.netPartnerCommission	The final commission amount payable to the partner after deducting all applicable fees and charge	2106.72
settlement.settlementCharge	Service fees charged for facilitating the settlement	4213.44
settlement.settlementChargeTax	Applicable tax amount levied on the settlement service charges	758.42
settlement.inrAmount	Settlement amount in rupees (INR).	16219.65
settlement.firafileDownloadUrl	Download link to FIRA file	fileDownloadUrl
settlement.status	Current status of the settlement.	INITIATED

Virtual account details

Active Event needs to be subscribed: Global Collect Virtual Account

Json

{
	"cmsProfileId": 260559,
	"event": "VIRTUAL_ACCOUNT_DETAILS",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"vAccounts": [
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "AUD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		},
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "BHD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		}
	]
}

Possible events and corresponding virtual account mapping

Event name	Virtual account status	Description
VIRTUAL_ACCOUNTS_ACTIVATED	ACTIVE	Virtual account is activated
VIRTUAL_ACCOUNTS_CREATED	INACTIVE / ACTIVE	If all the business required details are passed in the first go, VAs are created in ACTIVE state or INACTIVE
VIRTUAL_ACCOUNT_DETAILS	ACTIVE	Will contain all the details of the VA

Description

Sometimes there is mere might be a slight delay in creating some virtual accounts during onboarding and as a result, some of them might be missing in the Get All Collection Accounts API. Hence, when these missing account details are added, this webhook is triggered with all virtual account details (including the ones that were present before). This webhook contains information for all virtual account associated with a merchant along with cmsProfileId , signature and event.

Payload field description

Field	Description	Example
cmsProfileId	Merchant identifier	123
event	Webhook Event	VIRTUAL_ACCOUNT_DETAILS
merchant	Object contains the merchant_id to map the merchant created.	CF_7644f46b-ad82-472c-8d97-609d1a429eac
vAccounts.accountName	Account Name	John Doe
vAccounts.accountNumber	Account Number	GB11TCCL12345638242754
vAccounts.accountType	Account Type	iban
vAccounts.paymentType	Type of Payment	priority
vAccounts.bankName	Bank Name	The Currency Cloud Limited
vAccounts.bankAddress	Bank Address	12 Steward Street, The Steward Building, London, E1 6FQ, GB
vAccounts.bankCountry	Bank Country	GB
vAccounts.currency	Currency Code	BHD
vAccounts.routingCode	Routing Code	TCCLGB3L
vAccounts.routingCodeType	Routing Code Type	bic_swift
vAccounts.addedOn	The time when this virtual account was created	2023-03-28 14:43:30
vAccounts.vaccountId	Virtual Account Id	GB11T

Payments API

v2025-01-01

Other Versions

Webhook - Partner

Screenshots:

Transaction status

Possible events and corresponding transaction status mapping

Payload field description

Reversal status

Possible events and corresponding transaction status mapping

Payload field description

Settlement status

Possible events and corresponding settlement status mapping

Payload field description

Virtual account details

Possible events and corresponding virtual account mapping

Description

Payload field description

​Guide to subscribe webhook events

​Screenshots:

​Transaction status

​Possible events and corresponding transaction status mapping

​Payload field description

​Reversal status

​Possible events and corresponding transaction status mapping

​Payload field description

​Settlement status

​Possible events and corresponding settlement status mapping

​Payload field description

​Virtual account details

​Possible events and corresponding virtual account mapping

​Description

​Payload field description

Guide to subscribe webhook events

Screenshots:

Transaction status

Possible events and corresponding transaction status mapping

Payload field description

Reversal status

Possible events and corresponding transaction status mapping

Payload field description

Settlement status

Possible events and corresponding settlement status mapping

Payload field description

Virtual account details

Possible events and corresponding virtual account mapping

Description

Payload field description