Skip to main content
POST
/
routing
/
rule
/
evaluate
Routing - Rule Evaluate
curl --request POST \
  --url https://sandbox.hyperswitch.io/routing/rule/evaluate \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "created_by": "profile_123",
  "parameters": {},
  "fallback_output": [
    {
      "gateway_id": "authipay_1705"
    }
  ],
  "payment_id": "pay_abc123"
}
'
{
  "status": "success",
  "output": "<unknown>",
  "evaluated_output": [
    {
      "merchant_connector_id": "<string>"
    }
  ],
  "eligible_connectors": [
    {
      "merchant_connector_id": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://api-reference.hyperswitch.io/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
api-key
string
header
required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Body

application/json

Request body used to evaluate routing rules.

This API evaluates routing logic based on dynamic parameters like payment method, amount, country, card_bin, etc.

​
created_by
string
required

Identifier of the user/system triggering routing evaluation.

Example:

"created_by": "some_id"
Example:

"profile_123"

​
parameters
object
required

Dynamic parameters used during routing evaluation.

Each key represents a routing attribute.

Example fields:

  • payment_method
  • payment_method_type
  • amount
  • currency
  • authentication_type
  • card_bin
  • capture_method
  • business_country
  • billing_country
  • business_label
  • setup_future_usage
  • card_network
  • payment_type
  • mandate_type
  • mandate_acceptance_type
  • metadata

Example:

{
"payment_method": { "type": "enum_variant", "value": "card" },
"amount": { "type": "number", "value": 10 },
"currency": { "type": "str_value", "value": "INR" },
"authentication_type": { "type": "enum_variant", "value": "three_ds" },
"card_bin": { "type": "str_value", "value": "424242" },
"business_country": { "type": "str_value", "value": "IN" },
"setup_future_usage": { "type": "enum_variant", "value": "off_session" },
"card_network": { "type": "enum_variant", "value": "visa" },
"metadata": {
"type": "metadata_variant",
"value": { "key": "key1", "value": "value1" }
}
}

For the complete superset of supported routing keys, refer to routing_configs.keys in: https://github.com/juspay/decision-engine/blob/main/config/development.toml

​
fallback_output
object[]
required

Fallback connectors used if routing rule evaluation fails.

These connectors will be returned if no rule matches.

Example:

[
{
"gateway_name": "stripe",
"gateway_id": "mca_123"
}
]
​
payment_id
string | null

Payment ID for debugging and tracing routing decisions.

Example:

"payment_id": "pay_abc123"
Example:

"pay_abc123"

Response

Routing rules evaluated successfully

Response returned after routing evaluation.

Contains:

  • Routing status
  • Raw output structure (priority / volume_split)
  • Final evaluated connectors
  • Eligible connectors list
​
status
string
required

Status of routing evaluation.

Example:

"success"
Example:

"success"

​
output
any
required

Raw routing output returned by routing engine.

Possible structures:

  1. Volume Split:
{
"type": "volume_split",
"splits": [
{
"connector": { "gateway_name": "adyen", "gateway_id": "mca_124" },
"split": 60
},
{
"connector": { "gateway_name": "stripe", "gateway_id": "mca_123" },
"split": 40
}
]
}
  1. Priority:
{
"type": "priority",
"connectors": [
{ "gateway_name": "stripe", "gateway_id": "mca_123" },
{ "gateway_name": "adyen", "gateway_id": "mca_124" }
]
}
​
evaluated_output
object[]
required

Final connector(s) selected after evaluation.

Example:

[
{
"connector": "stripe",
"merchant_connector_id": "mca_123"
}
]
​
eligible_connectors
object[]
required