This chapter explains the Global Collections Webhooks.
Guide to Subscribe Webhook Events
- 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
{
"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
{
"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
| 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 |
| 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 |
| reversal.reason | The reason for which the transaction is being reversed. | Transaction rejected as per Cashfree's internal policy, Transaction value higher than the compliant limit |
| reversal.status | Status of the reversal of the transaction. | INITIATED, DONE |
| 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 |
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",
"id": "f16581f5-344c-40e8-be4b-e63cb5714a88",
"inrAmount": 16219.65,
"status": "INITIATED"
},
"status": "SETTLED",
"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 here. | 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.firafileDownloadUrl | Download link to FIRA file | fileDownloadUrl |
| settlement.expectedSettlementDate | Expected date of settlement. | 2023-08-30 |
| settlement.inrAmount | Settlement amount in rupees (INR). | 16219.65 |
| settlement.status | Current status of the settlement. | INITIATED |
Virtual Account Details
Active Event needs to be subscribed: Global Collect Virtual Account
{
"cmsProfileId": 260559,
"event": "VIRTUAL_ACCOUNT_DETAILS",
"merchant": {
"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
},
"vAccounts": [
{
"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"
},
{
"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.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 |