Decide Gateway

Core routing decision API. Given a payment context and a list of eligible gateways, returns the optimal gateway to route to.

POST /decide-gateway

cURL

sr_routing

curl --request POST \ --url http://localhost:8080/decide-gateway \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "merchantId": "test_merchant", "paymentInfo": { "paymentId": "pay_001", "amount": 1000, "currency": "USD", "country": "US", "customerId": "cust_123", "paymentType": "ORDER_PAYMENT", "paymentMethodType": "CARD", "paymentMethod": "CREDIT", "authType": "THREE_DS", "cardIsin": "411111" }, "eligibleGatewayList": [ "stripe", "paypal", "adyen" ], "rankingAlgorithm": "SR_BASED_ROUTING", "eliminationEnabled": false } '

200

sr_routing

{ "decided_gateway": "stripe", "routing_approach": "SR_SELECTION_V3_ROUTING", "gateway_priority_map": { "stripe": 0.94, "adyen": 0.87, "paypal": 0.72 }, "routing_dimension": "CARD_BRAND", "routing_dimension_level": "visa", "reset_approach": "NoReset", "is_scheduled_outage": false, "is_rust_based_decider": true, "latency": 8, "multi_objective_info": null }

Decide Gateway

Use case

Runs the core gateway decision flow for a payment. The same endpoint supports auth-rate routing, priority-list routing, debit/network routing, and network+SR hybrid routing.

Authentication

Protected. Send either Authorization: Bearer <jwt_token> or x-api-key: <api_key>. In sandbox, also send x-feature: decision-engine.

For local development, start with:

export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"

Request

• Method and path: POST /decide-gateway
• Parameters: none.
• Body: JSON body with merchantId, paymentInfo, eligibleGatewayList, and rankingAlgorithm. rankingAlgorithm must be one of SR_BASED_ROUTING, PL_BASED_ROUTING, NTW_BASED_ROUTING, or NTW_SR_HYBRID_ROUTING.

Example

SR based routing

curl --location "$BASE_URL/decide-gateway" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "eligibleGatewayList": ["stripe", "adyen", "checkout"],
  "rankingAlgorithm": "SR_BASED_ROUTING",
  "eliminationEnabled": true,
  "paymentInfo": {
    "paymentId": "pay_sr_001",
    "amount": 1000,
    "currency": "USD",
    "country": "US",
    "paymentType": "ORDER_PAYMENT",
    "paymentMethodType": "CARD",
    "paymentMethod": "CREDIT",
    "authType": "THREE_DS",
    "cardIsin": "424242"
  }
}'

Priority-list routing

curl --location "$BASE_URL/decide-gateway" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "eligibleGatewayList": ["stripe", "adyen", "checkout"],
  "rankingAlgorithm": "PL_BASED_ROUTING",
  "eliminationEnabled": true,
  "paymentInfo": {
    "paymentId": "pay_pl_001",
    "amount": 1000,
    "currency": "USD",
    "country": "US",
    "paymentType": "ORDER_PAYMENT",
    "paymentMethodType": "CARD",
    "paymentMethod": "CREDIT",
    "authType": "THREE_DS",
    "cardIsin": "424242"
  }
}'

Debit/network routing

curl --location "$BASE_URL/decide-gateway" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "eligibleGatewayList": ["stripe", "adyen"],
  "rankingAlgorithm": "NTW_BASED_ROUTING",
  "paymentInfo": {
    "paymentId": "pay_debit_001",
    "amount": 1000,
    "currency": "USD",
    "country": "US",
    "paymentType": "ORDER_PAYMENT",
    "paymentMethodType": "CARD",
    "paymentMethod": "DEBIT",
    "authType": "THREE_DS",
    "metadata": "{\"merchant_category_code\":\"merchant_category_code_0001\",\"acquirer_country\":\"US\",\"co_badged_card_data\":{\"card_type\":\"debit\",\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"]}}"
  }
}'

Multi-objective routing

curl --location "$BASE_URL/decide-gateway" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "eligibleGatewayList": ["stripe", "adyen", "checkout"],
  "rankingAlgorithm": "SR_BASED_ROUTING",
  "eliminationEnabled": true,
  "enableMultiObjective": true,
  "paymentInfo": {
    "paymentId": "pay_mo_001",
    "amount": 1000,
    "currency": "USD",
    "country": "US",
    "paymentType": "ORDER_PAYMENT",
    "paymentMethodType": "CARD",
    "paymentMethod": "CREDIT",
    "authType": "THREE_DS",
    "cardIsin": "424242"
  }
}'

Network + SR hybrid routing

curl --location "$BASE_URL/decide-gateway" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "eligibleGatewayList": ["stripe", "adyen"],
  "rankingAlgorithm": "NTW_SR_HYBRID_ROUTING",
  "paymentInfo": {
    "paymentId": "pay_hybrid_001",
    "amount": 1000,
    "currency": "USD",
    "country": "US",
    "paymentType": "ORDER_PAYMENT",
    "paymentMethodType": "CARD",
    "paymentMethod": "DEBIT",
    "authType": "THREE_DS",
    "metadata": "{\"merchant_category_code\":\"merchant_category_code_0001\",\"acquirer_country\":\"US\",\"co_badged_card_data\":{\"card_type\":\"debit\",\"issuer_country\":\"US\",\"is_regulated\":false,\"regulated_name\":null,\"card_networks\":[\"VISA\",\"NYCE\",\"PULSE\",\"STAR\"]}}"
  }
}'

Response

{
  "decided_gateway": "stripe",
  "gateway_priority_map": {
    "stripe": 0.94,
    "adyen": 0.91
  },
  "routing_approach": "SR_SELECTION_V3_ROUTING",
  "gateway_before_evaluation": "stripe",
  "debit_routing_output": {
    "co_badged_card_networks_info": [
      {
        "network": "NYCE",
        "saving_percentage": 1.2
      }
    ],
    "issuer_country": "US",
    "is_regulated": false,
    "card_type": "debit"
  },
  "is_rust_based_decider": true
}

Notes

• Use backend enum strings exactly; camelCase values such as NtwBasedRouting are invalid.
• Debit routing requires the merchant debit-routing flag to be enabled and debit metadata encoded as a JSON string in paymentInfo.metadata.
• Multi-objective routing is not a rankingAlgorithm value: it is a cost-aware post-step on SR-based scoring, toggled per request with enableMultiObjective or per merchant with the multi_objective_routing_enabled feature flag. When it runs, the response carries a multi_objective_info block, and routing_approach becomes SR_SELECTION_MULTI_OBJECTIVE when a cheaper gateway wins on expected value.
• A successful call emits analytics/audit events asynchronously.

Related

• Decide Gateway: SR Based Routing
• Decide Gateway: PL Based Routing
• Decide Gateway: Debit Routing
• Decide Gateway: Hybrid Routing
• Decide Gateway: Multi-Objective Routing
• Update Gateway Score

Authorizations

BearerAuthApiKeyAuth

Authorization · string · header · required

JWT token obtained from /auth/login

Body

application/json

merchantId · string · required

Example:

"test_merchant"

paymentInfo · object · required

Show child attributes

eligibleGatewayList · string[] · required

Example:

["stripe", "paypal", "adyen"]

rankingAlgorithm · enum<string> · required

Available options: SR_BASED_ROUTING, PL_BASED_ROUTING, NTW_BASED_ROUTING, NTW_SR_HYBRID_ROUTING

Example:

"SR_BASED_ROUTING"

eliminationEnabled · boolean · default: false

enableMultiObjective · boolean

Per-request override for the multi-objective (cost-aware) post-step. true forces it on, false forces it off; omitted falls back to the merchant's multi_objective_routing_enabled feature flag.

Response

200

application/json

Gateway decision result

decided_gateway · string

Example:

"stripe"

routing_approach · string

Routing approach used. SR_SELECTION_MULTI_OBJECTIVE indicates the multi-objective post-step promoted a cheaper gateway over the SR head.

Example:

"SR_SELECTION_V3_ROUTING"

gateway_priority_map · object

Show child attributes

Example:

{
  "stripe": 0.94,
  "adyen": 0.87,
  "paypal": 0.72
}

routing_dimension · string

routing_dimension_level · string

reset_approach · string

is_scheduled_outage · boolean

is_rust_based_decider · boolean

debit_routing_output · object

Show child attributes

latency · number

multi_objective_info · object | null

Populated when the multi-objective post-step ran (multi_objective_routing_enabled feature flag or enableMultiObjective request field, outside hedging). Null otherwise.

Show child attributes

fallback_gateways · string[]

Example:

["adyen"]

filter_wise_gateways · object | null

priority_logic_tag · string | null

priority_logic_output · object | null

gateway_mga_id_map · object | null

is_dynamic_mga_enabled · boolean

gateway_before_evaluation · string | null

Gateway the SR head selected before the multi-objective / debit-routing post-step replaced it.