> ## 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. # Decide Gateway > Core routing decision API. Given a payment context and a list of eligible gateways, returns the optimal gateway to route to. # 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 ` or `x-api-key: `. In sandbox, also send `x-feature: decision-engine`. For local development, start with: ```bash theme={null} export BASE_URL=http://localhost:8080 export AUTH_HEADER="Authorization: Bearer " # 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```json theme={null} { "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](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-sr-based) * [Decide Gateway: PL Based Routing](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-pl-based) * [Decide Gateway: Debit Routing](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-debit-routing) * [Decide Gateway: Hybrid Routing](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-hybrid-routing) * [Decide Gateway: Multi-Objective Routing](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-multi-objective) * [Update Gateway Score](/decision-engine-api-reference/api-reference/endpoint/score-feedback/updateGatewayScore) ## OpenAPI ````yaml decision_engine_openapi-specs.json POST /decide-gateway openapi: 3.1.0 info: title: Decision Engine description: >- Open-source payment gateway routing service by Juspay. Selects the optimal payment processor for each transaction in real-time using success-rate scoring, rule-based routing, and elimination logic. ## Authentication This API supports two authentication methods: 1. **JWT Bearer Token** - For dashboard/user sessions - Header: `Authorization: Bearer ` - Obtain via `/auth/login` endpoint 2. **API Key** - For service-to-service/programmatic access - Header: `x-api-key: DE_<64_char_hex>` - Create via `/api-key/create` endpoint Protected endpoints require one of these authentication methods. version: 1.4.0 contact: name: Juspay url: https://github.com/juspay/decision-engine license: name: AGPL-3.0 url: https://www.gnu.org/licenses/agpl-3.0.html servers: - url: http://localhost:8080 description: Local development - url: https://sandbox.hyperswitch.io description: 'Hyperswitch sandbox with x-feature: decision-engine' security: [] tags: - name: Health description: Service liveness, readiness, and diagnostics - name: Auth description: Dashboard auth and merchant selection - name: API Keys description: Service-to-service API key management - name: Gateway Decision description: Core routing decision APIs - name: Score Feedback description: Feed transaction outcomes back to improve SR scoring - name: Merchant Account description: Merchant configuration management - name: Routing Rules description: Euclid declarative routing rules engine - name: Rule Configuration description: Service-level SR/elimination config - name: Config description: Routing key and dimension metadata - name: Analytics description: ClickHouse-backed analytics and audit reads - name: Compatibility description: Legacy compatibility routes - name: Connector Costs - name: Merchant Features - name: Autopilot paths: /decide-gateway: post: tags: - Gateway Decision summary: Decide gateway description: >- Core routing decision API. Given a payment context and a list of eligible gateways, returns the optimal gateway to route to. The engine applies a sequence of filters (currency, card brand, auth type, EMI, etc.) then scores remaining gateways using success rate history, elimination status, and contract obligations. **Authentication:** Requires either JWT Bearer token or API Key. operationId: decideGateway requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DecideGatewayRequest' examples: sr_routing: summary: SR-based routing value: 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 debit_routing: summary: Debit/network-based routing value: merchantId: merchant_demo paymentInfo: paymentId: debit_001 amount: 1000 currency: USD 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":{"co_badged_card_networks":["VISA","NYCE","PULSE","STAR"],"issuer_country":"US","is_regulated":false,"regulated_name":null,"card_type":"debit"}} eligibleGatewayList: - stripe - adyen rankingAlgorithm: NTW_BASED_ROUTING eliminationEnabled: false hybrid_routing: summary: Hybrid SR + debit routing value: merchantId: test_merchant paymentInfo: paymentId: pay_003 amount: 750 currency: USD paymentType: ORDER_PAYMENT paymentMethodType: CARD paymentMethod: DEBIT eligibleGatewayList: - stripe - braintree - adyen rankingAlgorithm: NTW_SR_HYBRID_ROUTING eliminationEnabled: false multi_objective_routing: summary: Multi-objective routing value: merchantId: merchant_demo paymentInfo: paymentId: mo_001 amount: 1000 currency: USD country: US paymentType: ORDER_PAYMENT paymentMethodType: CARD paymentMethod: CREDIT authType: THREE_DS cardIsin: '424242' eligibleGatewayList: - stripe - adyen - checkout rankingAlgorithm: SR_BASED_ROUTING eliminationEnabled: true enableMultiObjective: true responses: '200': description: Gateway decision result content: application/json: schema: $ref: '#/components/schemas/DecidedGateway' examples: sr_routing: summary: SR-based routing value: 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 debit_routing: summary: Debit/network-based routing value: decided_gateway: stripe gateway_priority_map: null filter_wise_gateways: null priority_logic_tag: null routing_approach: NTW_BASED_ROUTING gateway_before_evaluation: null priority_logic_output: null debit_routing_output: co_badged_card_networks_info: - network: NYCE saving_percentage: 1.2 - network: PULSE saving_percentage: 0.9 - network: VISA saving_percentage: 0.1 issuer_country: US is_regulated: false regulated_name: null card_type: debit reset_approach: NO_RESET routing_dimension: null routing_dimension_level: null is_scheduled_outage: false is_dynamic_mga_enabled: false gateway_mga_id_map: null is_rust_based_decider: true multi_objective_info: null hybrid_routing: summary: Hybrid SR + debit routing value: decided_gateway: stripe routing_approach: NTW_BASED_ROUTING debit_routing_output: co_badged_card_networks_info: - network: NYCE saving_percentage: 1.2 - network: PULSE saving_percentage: 0.9 issuer_country: US is_regulated: false regulated_name: null card_type: debit reset_approach: NO_RESET is_scheduled_outage: false is_rust_based_decider: true multi_objective_info: null multi_objective_routing: summary: Multi-objective routing — auth won (SR head retained) value: decided_gateway: adyen fallback_gateways: - stripe - checkout gateway_priority_map: adyen: 0.65 checkout: 0.58 stripe: 0.65 filter_wise_gateways: null priority_logic_tag: null routing_approach: SR_SELECTION_V3_ROUTING gateway_before_evaluation: adyen priority_logic_output: isEnforcement: false gws: - stripe - adyen - checkout priorityLogicTag: null gatewayReferenceIds: {} primaryLogic: null fallbackLogic: null debit_routing_output: null reset_approach: NO_RESET routing_dimension: ORDER_PAYMENT, CARD, DEBIT, DEBIT routing_dimension_level: CARD_LEVEL is_scheduled_outage: false is_dynamic_mga_enabled: false gateway_mga_id_map: null is_rust_based_decider: true latency: 3 multi_objective_info: outcome: AUTH_WON reason: >- SR head retained — it is the highest expected-value PSP (3 ranked on EV). srHead: psp: adyen authRate: 0.65 costBps: 156.94736842105263 chosen: psp: adyen authRate: 0.65 costBps: 156.94736842105263 costSavedBps: null qualifiedCount: 3 margin: 1 evGapTop2: 0.013780000000000014 multi_objective_cost_won: summary: >- Multi-objective routing — cost won (cheaper gateway promoted) value: decided_gateway: adyen fallback_gateways: - stripe - checkout gateway_priority_map: stripe: 0.94 adyen: 0.91 checkout: 0.88 routing_approach: SR_SELECTION_MULTI_OBJECTIVE gateway_before_evaluation: stripe reset_approach: NO_RESET routing_dimension: ORDER_PAYMENT,CARD,CREDIT,UNKNOWN routing_dimension_level: CARD_LEVEL is_scheduled_outage: false is_dynamic_mga_enabled: false is_rust_based_decider: true multi_objective_info: outcome: COST_WON reason: >- Promoted 'adyen' over 'stripe' on expected value — saves 80.00 bps for 3.00pp auth. srHead: psp: stripe authRate: 0.94 costBps: 180 chosen: psp: adyen authRate: 0.91 costBps: 100 costSavedBps: 80 qualifiedCount: 3 margin: 0.2 evGapTop2: 0.00182 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: DecideGatewayRequest: type: object required: - merchantId - paymentInfo - eligibleGatewayList - rankingAlgorithm properties: merchantId: type: string example: test_merchant paymentInfo: $ref: '#/components/schemas/PaymentInfo' eligibleGatewayList: type: array items: type: string example: - stripe - paypal - adyen rankingAlgorithm: type: string enum: - SR_BASED_ROUTING - PL_BASED_ROUTING - NTW_BASED_ROUTING - NTW_SR_HYBRID_ROUTING example: SR_BASED_ROUTING eliminationEnabled: type: boolean default: false enableMultiObjective: type: boolean description: >- 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. DecidedGateway: type: object properties: decided_gateway: type: string example: stripe routing_approach: type: string example: SR_SELECTION_V3_ROUTING description: >- Routing approach used. SR_SELECTION_MULTI_OBJECTIVE indicates the multi-objective post-step promoted a cheaper gateway over the SR head. gateway_priority_map: type: object additionalProperties: type: number example: stripe: 0.94 adyen: 0.87 paypal: 0.72 routing_dimension: type: string routing_dimension_level: type: string reset_approach: type: string is_scheduled_outage: type: boolean is_rust_based_decider: type: boolean debit_routing_output: $ref: '#/components/schemas/DebitRoutingOutput' latency: type: number multi_objective_info: allOf: - $ref: '#/components/schemas/MultiObjectiveInfo' nullable: true description: >- Populated when the multi-objective post-step ran (multi_objective_routing_enabled feature flag or enableMultiObjective request field, outside hedging). Null otherwise. ErrorResponse: type: object properties: error: type: string message: type: string PaymentInfo: type: object required: - paymentId - amount - currency - paymentType - paymentMethodType - paymentMethod properties: paymentId: type: string example: pay_001 amount: type: number format: double example: 1000 currency: type: string description: ISO 4217 currency code. example: USD country: type: string nullable: true description: ISO 3166-1 alpha-2 country code. example: US customerId: type: string nullable: true example: cust_123 udfs: type: object nullable: true description: User-defined fields, keyed udf1..udf20. additionalProperties: type: string preferredGateway: type: string nullable: true description: Pins routing to a specific gateway when set. paymentType: type: string enum: - ORDER_PAYMENT - MANDATE_REGISTER - EMANDATE_REGISTER - MANDATE_PAYMENT - EMANDATE_PAYMENT - TPV_PAYMENT - TPV_EMANDATE_REGISTER - TPV_MANDATE_REGISTER - TPV_EMANDATE_PAYMENT - TPV_MANDATE_PAYMENT - PARTIAL_CAPTURE - PARTIAL_VOID - VAN_PAYMENT - MOTO_PAYMENT - UNKNOWN example: ORDER_PAYMENT metadata: type: string nullable: true internalMetadata: type: string nullable: true isEmi: type: boolean nullable: true emiBank: type: string nullable: true emiTenure: type: integer format: int32 nullable: true paymentMethodType: type: string description: >- Connector-defined payment method type, e.g. CARD, UPI, WALLET, NETBANKING. example: CARD paymentMethod: type: string description: Connector-defined payment method, e.g. CREDIT, DEBIT, GPAY. example: CREDIT paymentSource: type: string nullable: true authType: type: string nullable: true enum: - ATMPIN - THREE_DS - THREE_DS2 - OTP - OBO_OTP - VIES - NO_THREE_DS - NETWORK_TOKEN - MOTO - FIDO - CTP example: THREE_DS cardIssuerBankName: type: string nullable: true cardIsin: type: string nullable: true example: '411111' cardType: type: string nullable: true description: e.g. CREDIT, DEBIT, PREPAID, UPI, NB. example: CREDIT cardSwitchProvider: type: string nullable: true cardProgram: type: string nullable: true cardIssuerCountry: type: string nullable: true channel: type: string nullable: true description: 'Acceptance channel: ecom / pos / contactless.' DebitRoutingOutput: type: object properties: co_badged_card_networks_info: type: array items: type: object properties: network: type: string example: NYCE saving_percentage: type: number example: 1.2 issuer_country: type: string example: US is_regulated: type: boolean example: false regulated_name: type: string nullable: true card_type: type: string example: Debit MultiObjectiveInfo: type: object description: >- Present when the multi-objective (cost-aware) post-step ran. Explains why the gateway was picked: the SR head was kept (AUTH_WON) or a higher economic-value PSP was promoted (COST_WON). Economic value is auth rate × settlement value, where settlement value = txn amount − cost of payment processing (acquirer, issuer & network fee). properties: outcome: type: string enum: - COST_WON - AUTH_WON example: COST_WON reason: type: string example: >- Promoted 'adyen' over 'stripe' on expected value — saves 80.00 bps for 3.00pp auth. srHead: allOf: - $ref: '#/components/schemas/PspSummary' nullable: true description: The PSP the SR scorer would have picked. chosen: allOf: - $ref: '#/components/schemas/PspSummary' nullable: true description: The PSP the post-step actually chose. Equals srHead when auth won. costSavedBps: type: number nullable: true description: >- Fee saved in bps when outcome is COST_WON (srHead.costBps - chosen.costBps). example: 80 qualifiedCount: type: integer description: Number of PSPs that had cost data and were ranked on expected value. example: 3 margin: type: number description: >- Merchant margin (fraction of ticket) applied for this transaction. Configured via the successRate config margin field; defaults to 1.0. example: 0.2 evGapTop2: type: number nullable: true description: >- Expected-value gap between the top-two EV-ranked PSPs, as a fraction of ticket. Null when fewer than two PSPs had cost data. example: 0.00182 PspSummary: type: object properties: psp: type: string example: adyen authRate: type: number example: 0.91 costBps: type: number nullable: true example: 100 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from /auth/login ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key created via /api-key/create ````