Webhook - Partner

This chapter explains the Global Collections Webhooks.

Guide to Subscribe Webhook Events

  1. Visit https://partner.cashfree.com login with your partner credentials
  2. 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
  3. Add your webhook URL and subscribe events Global Collect Transaction, Global Collect Settlement & Global Collect Virtual Account
  4. 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 NamePayment StatusDescription
INTERNATIONAL_PAYMENT_COLLECTEDCOMPLETEDReceived payment
INTERNATIONAL_PAYMENT_BLOCKEDBLOCKEDThe transaction has been blocked due to the specified reason in the designated field.
INTERNATIONAL_PAYMENT_AWAITING_DETAILSCOMPLETEDWaiting for the details of the transaction

Payload Field Description

FieldDescriptionExample
amountThe foreign currency amount sent4.50
currencyThree character ISO code. View list of supported currencies here.GBP
cmsProfileIdMerchant identifier123
eventWebhook eventINTERNATIONAL_AMOUNT_COLLECTED
paymentTimeThe time at which the payment was initiated.2022-12-29 13:42:54
referenceIdCashfree Payments transaction identifier63
remarksRemarks passed by the sender.Sample Remark
reasonReason regarding the transaction being blocked.Transaction value below the allowed limit
remitterAccountThe bank account number of the person who sends the money.1223456789
remitterAddressThe address of the person who sends the money.Dummy Address
remitterBicBank identifier code for the remitter.TRWIBEB1XXX
remitterCountryThe country from which the money is sent.GB
remitterNameThe name of the remitter who is sending the money.John Doe
remitterRoutingCodeThe routing code of the remitter's bank.TLG0123
statusStatus of FCY (foreign currency leg) of transaction.COMPLETED, FAILED, AWAITING_DETAILS
updatedStatusTimeThe time of the last status update.2022-12-29 13:50:35
vAccountIdIdentifier of the virtual account.97836
vAccountNumberAccount number to which the payment was done.GB38TCCL12345687997836
merchantObject contains merchant_id used while creating merchantCF_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 NameReversal StatusTransaction StatusDescription
INTERNATIONAL_PAYMENT_REVERSAL_INITIATEDINITIATEDREVERSAL_INITIATEDReversal for the transaction is initiated.
INTERNATIONAL_PAYMENT_REVERSAL_DONEDONEREVERSAL_DONEReversal for the transaction is completed. The funds have been successfully returned to the sender.

Payload Field Description

FieldDescriptionExample
amountThe foreign currency amount sent4.50
currencyThree character ISO code. View list of supported currencies here.GBP
cmsProfileIdMerchant identifier123
eventWebhook eventINTERNATIONAL_AMOUNT_COLLECTED
paymentTimeThe time at which the payment was initiated.2022-12-29 13:42:54
referenceIdCashfree Payments transaction identifier63
remarksRemarks passed by the sender.Sample Remark
remitterAccountThe bank account number of the person who sends the money.1223456789
remitterAddressThe address of the person who sends the money.Dummy Address
remitterBicBank identifier code for the remitter.TRWIBEB1XXX
remitterCountryThe country from which the money is sent.GB
remitterNameThe name of the remitter who is sending the money.John Doe
remitterRoutingCodeThe routing code of the remitter's bank.TLG0123
reversal.reasonThe reason for which the transaction is being reversed.Transaction rejected as per Cashfree's internal policy,
Transaction value higher than the compliant limit
reversal.statusStatus of the reversal of the transaction.INITIATED, DONE
statusStatus of FCY (foreign currency leg) of transaction.COMPLETED, FAILED, AWAITING_DETAILS
updatedStatusTimeThe time of the last status update.2022-12-29 13:50:35
vAccountIdIdentifier of the virtual account.97836
vAccountNumberAccount number to which the payment was done.GB38TCCL12345687997836
merchantObject contains merchant_id used while creating merchantCF_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 NameSettlement StatusDescription
INR_SETTLEMENT_INITIATEDINITIATEDThe settlement is initiated.
INR_SETTLEMENT_APPROVEDSETTLEDThe settlement is settled.
INR_SETTLEMENT_REJECTEDREJECTEDThe settlement is rejected.
FIRA_FILE_RECEIVEDSETTLEDFIRA file received for the settlement.

Payload Field Description

FieldDescriptionExample
amountThe foreign currency amount sent4.50
currencyThree character ISO code. View list of supported currencies here.GBP
cmsProfileIdMerchant identifier123
eventWebhook eventINTERNATIONAL_AMOUNT_COLLECTED
merchantObject contains the merchant_id to map the merchant created.CF_7644f46b-ad82-472c-8d97-609d1a429eac
paymentTimeThe time at which the payment was initiated.2022-12-29 13:42:54
referenceIdCashfree Payments transaction identifier63
remarksRemarks passed by the sender.Sample Remark
remitterAccountThe bank account number of the person who sends the money.1223456789
remitterAddressThe address of the person who sends the money.Dummy Address
remitterBicBank identifier code for the remitter.TRWIBEB1XXX
remitterCountryThe country from which the money is sent.GB
remitterNameThe name of the remitter who is sending the money.John Doe
remitterRoutingCodeThe routing code of the remitter's bank.TLG0123
statusStatus of FCY (foreign currency leg) of transaction.COMPLETED, FAILED
updatedStatusTimeThe time of the last status update.2022-12-29 13:50:35
vAccountIdIdentifier of the virtual account.97836
vAccountNumberAccount number to which the payment was made.GB38TCCL12345687997836
paymentRailPayment Network used to make the paymentACH,EFT,FPS,SEPA,SWIFT,FEDWIRE
settlement.idUnique reference ID for the settlement since the payment can have multiple settlements.b84a7c4c-2ce0-48ca-9b86-2a2c9ad5a35d
settlement.firafileDownloadUrlDownload link to FIRA filefileDownloadUrl
settlement.expectedSettlementDateExpected date of settlement.2023-08-30
settlement.inrAmountSettlement amount in rupees (INR).16219.65
settlement.statusCurrent 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 NameVirtual Account StatusDescription
VIRTUAL_ACCOUNTS_ACTIVATEDACTIVEVirtual account is activated
VIRTUAL_ACCOUNTS_CREATEDINACTIVE / ACTIVEIf all the business required details are passed in the
first go VAs are created in ACTIVE state or INACTIVE
VIRTUAL_ACCOUNT_DETAILSACTIVEWill 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

FieldDescriptionExample
cmsProfileIdMerchant identifier123
eventWebhook EventVIRTUAL_ACCOUNT_DETAILS
merchantObject contains the merchant_id to map the merchant created.CF_7644f46b-ad82-472c-8d97-609d1a429eac
vAccounts.accountNumberAccount NumberGB11TCCL12345638242754
vAccounts.accountTypeAccount Typeiban
vAccounts.paymentTypeType of Paymentpriority
vAccounts.bankNameBank NameThe Currency Cloud Limited
vAccounts.bankAddressBank Address12 Steward Street, The Steward Building, London, E1 6FQ, GB
vAccounts.bankCountryBank CountryGB
vAccounts.currencyCurrency CodeBHD
vAccounts.routingCodeRouting CodeTCCLGB3L
vAccounts.routingCodeTypeRouting Code Typebic_swift
vAccounts.addedOnThe time when this virtual account was created2023-03-28 14:43:30
vAccounts.vaccountIdVirtual Account IdGB11T