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
}
'

{
  "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
}

POST

decide-gateway

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
}
'

{
  "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.

Authorizations

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

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

Health Diagnostics Update Gateway Score

Overview

OpenAPI: Health

OpenAPI: Gateway Decision

OpenAPI: Score Feedback

OpenAPI: Merchant Account

OpenAPI: Routing Rules

OpenAPI: Rule Configuration

OpenAPI: Auth And API Keys

OpenAPI: Analytics

OpenAPI: Compatibility And Config

OpenAPI: Connector Costs & Ingestion

OpenAPI: Feature Flags & Autopilot

API Examples (curl flows)

Decide Gateway

Decide Gateway

Use case

Authentication

Request

Example

SR based routing

Priority-list routing

Debit/network routing

Multi-objective routing

Network + SR hybrid routing

Response

Notes

Authorizations

Body

Response

​Decide Gateway

​Use case

​Authentication

​Request

​Example

​SR based routing

​Priority-list routing

​Debit/network routing

​Multi-objective routing

​Network + SR hybrid routing

​Response

​Notes

​Related

Authorizations

Body

Response

Decide Gateway

Use case

Authentication

Request

Example

SR based routing

Priority-list routing

Debit/network routing

Multi-objective routing

Network + SR hybrid routing

Response

Notes

Related