Route Payloads

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.

The table below lists the Webhook events available for Route.

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.

Do Not Parse or Cast the Webhook Request Body

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.