Route Webhook Events

Route enables businesses to split payments among third parties, sellers, or bank accounts while managing settlements, refunds, and vendor payments in a one-to-many model.

List of Route Webhook Events

The table below lists the webhook events available for Route.

Sample Payloads

Given below are the sample payloads for Route webhook events.

Transfer Processed

{
   "entity":"event",
   "account_id":"acc_CJoeHMNpi0nC7k",
   "event":"transfer.processed",
   "contains":[
      "transfer"
   ],
   "payload":{
      "transfer":{
         "entity":{
            "id":"trf_EB1gHgrzOZff6d",
            "entity":"transfer",
            "status":"processed",
            "settlement_status":null,
            "source":"order_EB1gHfAfmr65cS",
            "recipient":"acc_CNo3jSI8OkFJJJ",
            "amount":100,
            "currency":"INR",
            "amount_reversed":0,
            "notes":{
               "branch":"Acme Corp Bangalore South",
               "name":"Saurav Kumar"
            },
            "fees":1,
            "tax":0,
            "on_hold":false,
            "on_hold_until":null,
            "recipient_settlement_id":null,
            "created_at":1580461276,
            "linked_account_notes":[
               "branch"
            ],
            "processed_at":1580461335,
            "error":{
               "code":null,
               "description":null,
               "field":null,
               "source":null,
               "step":null,
               "reason":null
            }
         }
      }
   },
   "created_at":1580461335
}

Settlement Processed

Transfer Failed

{
   "entity":"event",
   "account_id":"acc_CJoeHMNpi0nC7k",
   "event":"transfer.failed",
   "contains":[
      "transfer"
   ],
   "payload":{
      "transfer":{
         "entity":{
            "id":"trf_EB1gHgrzOZff6d",
            "entity":"transfer",
            "status":"failed",
            "settlement_status":null,
            "source":"order_EB1gHfAfmr65cS",
            "recipient":"acc_CNo3jSI8OkFJJJ",
            "amount":100,
            "currency":"INR",
            "amount_reversed":0,
            "notes":{
               "branch":"Acme Corp Bangalore South",
               "name":"Saurav Kumar"
            },
            "fees":1,
            "tax":0,
            "on_hold":false,
            "on_hold_until":null,
            "recipient_settlement_id":null,
            "created_at":1580461276,
            "linked_account_notes":[
               "branch"
            ],
            "processed_at":null,
            "error":{
               "code":"BAD_REQUEST_TRANSFER_INSUFFICIENT_BALANCE",
               "description":"Transfer failed due to insufficient balance",
               "field":null,
               "source":"transfer",
               "step":"balance_check",
               "reason":"insufficient_balance"
            }
         }
      }
   },
   "created_at":1580461335
}

Product Route Under Review

Product Route Needs Clarification

{
  "entity": "event",
  "account_id": "acc_QTzf1oMb6lfvIL",
  "event": "product.route.needs_clarification",
  "contains": [
    "merchant_product"
  ],
  "payload": {
    "merchant_product": {
      "entity": {
        "id": "acc_prd_QTzgAPhwEwsO9Z",
        "merchant_id": "acc_QTzf1oMb6lfvIL",
        "activation_status": "needs_clarification"
      },
      "data": {
        "requirements": [
          {
            "field_reference": "settlements.ifsc_code",
            "resolution_url": "/accounts/acc_QTzf1oMb6lfvIL/products/acc_prd_QTzgAPhwEwsO9Z",
            "reason_code": "needs_clarification",
            "description": "Max retry exceeded for bank account details.",
            "status": "required"
          },
          {
            "field_reference": "settlements.beneficiary_name",
            "resolution_url": "/accounts/acc_QTzf1oMb6lfvIL/products/acc_prd_QTzgAPhwEwsO9Z",
            "reason_code": "needs_clarification",
            "description": "Max retry exceeded for bank account details.",
            "status": "required"
          },
          {
            "field_reference": "settlements.account_number",
            "resolution_url": "/accounts/acc_QTzf1oMb6lfvIL/products/acc_prd_QTzgAPhwEwsO9Z",
            "reason_code": "needs_clarification",
            "description": "Max retry exceeded for bank account details.",
            "status": "required"
          }
        ]
      }
    }
  },
  "created_at": 1747047833
}

Product Route Activated

Watch Out!

If you have changed your webhook secret, remember to use the old secret for webhook signature validation while retrying older requests. Using the new secret will lead to a signature mismatch.
While generating a signature at your end, ensure that the webhook body is passed as an argument in the raw webhook request body. Do not parse or cast the webhook request body.