Hyperswitch 决策引擎 API 参考：Decision Engine 全端点 Schema 体系、访问控制与核心路由接口详解

2026-09-05 13:59:34作者：裘旻烁

Open source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation

项目地址：https://gitcode.com/GitHub_Trending/hy/hyperswitch

本文基于 Hyperswitch 仓库中的 Decision Engine API 参考文档，系统讲解这套“schema-backed”端点参考的组织方式：如何理解 API Guide 与 OpenAPI Reference 两种查阅面、四类访问权限（Public / Admin bootstrap / Protected / Sandbox）的鉴权边界、全部端点家族的完整清单，以及核心接口 POST /decide-gateway、POST /update-gateway-score、POST /routing/create 的请求模型与可复制的 curl 示例。读完本文，你可以直接在本地或沙箱环境中完成 Decision Engine 的冒烟测试，并精确定位每个端点的请求/响应 Schema。

两种查阅面：API Guide 与 OpenAPI Reference

Hyperswitch 仓库在 api-reference/decision-engine-api-reference/ 下为决策引擎（Decision Engine）维护了两套互补的文档面，原文档给出的定位如下：

查阅面	适用场景
API Guide	面向任务的 `curl` 示例、完整端到端流程、请求变体（可复制粘贴直接运行）
API Reference（本文主题）	精确的请求/响应 Schema，每个端点一页，附带交互式 Playground

这里的 API Reference 并不是手写的静态页面，而是由 OpenAPI 契约 api-reference/decision_engine_openapi-specs.json 生成的（spec 版本 1.4.0，OpenAPI 3.1.0）。每个端点页面（如 decideGateway.mdx）的文件头中都有 openapi: "decision_engine_openapi-specs.json POST /decide-gateway" 这样的映射声明，指向 spec 中对应的 operation，页面正文再补充 Use case、认证要求、可运行示例和注意事项。

适用前提与运行环境：spec 的 servers 定义了两种地址——本地开发 http://localhost:8080，以及通过 Hyperswitch 网关提供的沙箱 https://sandbox.hyperswitch.io（需附加 x-feature: decision-engine 头）。本地启动方式（Docker Compose profile、源码构建、Helm）在 local-setup.md 中有完整说明；启动后用 curl http://localhost:8080/health 返回 {"message":"Health is good"} 即可确认服务就绪。

访问控制：四类访问边界

API 参考的核心内容之一是端点按鉴权方式划分的四个访问类。下表整合了原文档的 Access classes 表格，并补充了 API Guide 中关于租户头（x-tenant-id）的细化说明：

访问类	路由	鉴权要求
Public	`GET /health`、`GET /health/ready`、`GET /health/diagnostics`、`POST /auth/signup`、`POST /auth/login`	无
Admin bootstrap	`POST /merchant-account/create`	Admin secret（部署时配置的密钥）
Protected	所有 routing、decision、score 更新、rule 配置、API key、商户读/删、analytics、audit、config 及已认证的 auth 路由	`Authorization: Bearer <jwt_token>` 或 `x-api-key: <api_key>`
Sandbox	通过 `https://sandbox.hyperswitch.io` 提供的任意 Decision Engine 路由	上述鉴权规则 + `x-feature: decision-engine`

两种鉴权凭证的定位（来自 OpenAPI spec 的 info 描述）：

JWT Bearer Token：面向 dashboard / 用户会话，通过 POST /auth/login 获取；
API Key：面向服务到服务的程序化调用，格式为 DE_<64_char_hex>，通过 POST /api-key/create 创建。

一个容易踩坑的细节（API Guide 中特别警告）：x-tenant-id 头没有回退机制——在需要它的路线上（全部 GET /analytics/*、/health/diagnostics、POST /gateway-score/reset）省略它，即使鉴权头有效也会直接失败并返回 TE_03: x-tenant-id not found in headers。而 /decide-gateway、/routing/*、/rule/*、/merchant-account/*、/update-gateway-score、/auth/*、/api-key/* 等路线会在内部解析租户，不需要该头。

统一的请求头环境变量约定（可复制到 shell 中复用）：

# Base URL — 本地源码构建或 Docker Compose
export BASE_URL=http://localhost:8080
# 沙箱（经 Hyperswitch 路由），如适用
# export BASE_URL=https://sandbox.hyperswitch.io

# 受保护端点接受 dashboard JWT 或 API key 二者之一
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# export AUTH_HEADER="x-api-key: DE_<api_key>"

# 仅沙箱使用的路由头
export FEATURE_HEADER="x-feature: decision-engine"

# 仅 analytics 路由、/health/diagnostics、/gateway-score/reset 需要
export TENANT_HEADER="x-tenant-id: public"

端点家族总览：从 OpenAPI spec 还原的完整清单

原文档按家族（Family）组织了端点导航页。以 spec 文件为权威来源核对后，各家族的完整路由与方法如下（原文档未列出的 Connector Costs、Merchant Features、Autopilot 三个家族也一并给出，便于对照端点页面目录）：

Health（健康检查）

GET /health（healthCheck，公开）
GET /health/ready（healthReady，公开）
GET /health/diagnostics（healthDiagnostics，公开但需 x-tenant-id）

Auth And Onboarding（认证与入驻）

POST /auth/signup（signup，公开）
POST /auth/login（login，公开）
POST /auth/logout（logout）
GET /auth/me（me，当前用户）
GET /auth/merchants（listUserMerchants）
POST /auth/switch-merchant（switchMerchant）
POST /onboarding/merchant（onboardMerchant，dashboard 侧创建商户）

API Keys

POST /api-key/create（createApiKey）
GET /api-key/list/{merchant_id}（listApiKeys）
DELETE /api-key/{key_id}（revokeApiKey）

Merchant Account

POST /merchant-account/create（createMerchant，Admin secret 鉴权；商户 ID 是后续所有路由与打分调用的主标识）
GET /merchant-account/{merchant_id}（getMerchant）
DELETE /merchant-account/{merchant_id}（deleteMerchant）
GET /merchant-account/{merchant_id}/debit-routing（getMerchantDebitRouting）
POST /merchant-account/{merchant_id}/debit-routing（updateMerchantDebitRouting）

Gateway Decision（核心决策）

POST /decide-gateway（decideGateway，核心路由决策）
POST /decision_gateway（legacyDecisionGateway，旧版兼容路由）
POST /update-gateway-score（updateGatewayScore，结果反馈）
POST /update-score（legacyUpdateScore，旧版兼容路由）

Routing Rules（Euclid 声明式规则引擎）

POST /routing/create（createRoutingRule，支持 advanced / priority / single / volume_split 四类算法）
POST /routing/activate（activateRoutingRule）
POST /routing/deactivate（deactivateRoutingRule）
POST /routing/list/{created_by}（listRoutingRules）
POST /routing/list/active/{created_by}（getActiveRoutingRule）
POST /routing/evaluate（evaluateRoutingRule，对给定支付上下文做“预览”评估，不产生真实交易）
POST /routing/hybrid（hybridRouting，混合路由评估）

Rule Configuration（服务级 SR / elimination 配置）

POST /rule/create（createRuleConfig）
POST /rule/get（getRuleConfig）
POST /rule/update（updateRuleConfig）
POST /rule/delete（deleteRuleConfig）

Config

GET /config/routing-keys（getRoutingConfig，路由键与维度元数据）
POST /config-sr-dimension（configSrDimension，配置 SR 维度）

Analytics（ClickHouse 支撑的分析与审计读端点）

GET /analytics/overview（analyticsOverview）
GET /analytics/gateway-scores（analyticsGatewayScores）
GET /analytics/decisions（analyticsDecisions）
GET /analytics/routing-stats（analyticsRoutingStats）
GET /analytics/log-summaries（analyticsLogSummaries）
GET /analytics/payment-audit（analyticsPaymentAudit）
GET /analytics/preview-trace（analyticsPreviewTrace）
GET /analytics/cost-savings（analyticsCostSavings）
GET /analytics/routing-events（analyticsRoutingEvents）
GET /analytics/experiment/{experiment_id}/results（analyticsExperimentResults，A/B 实验结果）
GET /analytics/experiment/{experiment_id}/transactions（analyticsExperimentTransactions，A/B 实验交易）

以上全部 Analytics 端点均需 BearerAuth 或 ApiKeyAuth 之外再附加 x-tenant-id。

原文档未列出、但 spec 中存在的三个家族

从 spec 的 tag 列表看，还包含以下端点家族（端点页面位于 endpoint/connector-costs/、endpoint/features/ 目录）：

Connector Costs：GET/PUT/DELETE /merchant-account/{merchant_id}/connectors/*（凭证管理）、/connector-fees（费率列表）、/cost-clusters（成本簇）、/cost-coverage（成本覆盖率）、/cost-ingestions（结算/发票成本数据导入）、/cost-price-changes、/invoice-addons、/invoice-reconciliation；
Merchant Features：GET /merchant-account/{merchant_id}/features（getMerchantFeatures）、POST /merchant-account/{merchant_id}/features/{feature}（updateMerchantFeature，商户级功能开关）；
Autopilot：POST /gateway-score/reset（resetGatewayScores，硬性重置网关分数，供模拟运行使用）。

核心端点实战：/decide-gateway 与 /update-gateway-score

这一节继承端点参考页与 API Guide 的可复制示例，构成最完整的“决策 → 反馈”闭环。

POST /decide-gateway：核心路由决策

请求体包含 merchantId、paymentInfo、eligibleGatewayList 与 rankingAlgorithm，其中 rankingAlgorithm 必须是以下四个枚举值之一：

策略	请求值
成功率（授权率）路由	`SR_BASED_ROUTING`
优先级列表路由	`PL_BASED_ROUTING`
借记/卡组路由	`NTW_BASED_ROUTING`
卡组 + SR 混合路由	`NTW_SR_HYBRID_ROUTING`

SR 路由示例：

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

借记路由示例（注意 paymentMethod 为 DEBIT，且借记元数据须以 JSON 字符串形式编码在 paymentInfo.metadata 中，包含 merchant_category_code、acquirer_country、co_badged_card_data 等字段）：

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\"]}}"
  }
}'

多目标（成本感知）路由示例——注意它不是 rankingAlgorithm 的取值，而是在 SR 打分之上的后处理步骤，按请求用 enableMultiObjective 开启，或按商户用 multi_objective_routing_enabled 功能开关开启：

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

成功响应示例：

{
  "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 原文归纳）：

必须使用后端枚举字符串原文；camelCase 取值（如 NtwBasedRouting）无效；
借记路由要求商户的 debit-routing 标志已开启，且借记元数据编码在 paymentInfo.metadata 的 JSON 字符串中；
多目标路由生效时，响应携带 multi_objective_info 块；当更便宜的网关在期望值上胜出时，routing_approach 变为 SR_SELECTION_MULTI_OBJECTIVE；
成功调用会异步发出 analytics / audit 事件。

POST /update-gateway-score：把交易结果反馈给 SR 模型

每次授权完成后调用，让引擎的 SR 数据保持准确。请求体包含 merchantId、paymentId、gateway、status，以及可选的 gatewayReferenceId、enforceDynamicRoutingFailure、txnLatency、errorInfo、isSmartRetry：

curl --location "$BASE_URL/update-gateway-score" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "paymentId": "pay_sr_001",
  "gateway": "stripe",
  "status": "CHARGED",
  "gatewayReferenceId": "stripe_ref_001",
  "enforceDynamicRoutingFailure": false,
  "txnLatency": { "gatewayLatency": 120.5 }
}'

响应：

{
  "message": "Gateway score updated successfully",
  "merchant_id": "merchant_demo",
  "gateway": "stripe",
  "payment_id": "pay_sr_001"
}

Schema 层面的几个易错点：

status 必须是交易状态值（CHARGED、AUTHORIZATION_FAILED、AUTHENTICATION_FAILED、JUSPAY_DECLINED、FAILURE 等），小写值（如 success）会被 400 拒绝；
支付属性（金额、币种、支付方式、认证类型）不在此请求体中——引擎已从该 paymentId 对应的 /decide-gateway 调用中持有这些信息；
无法识别的字段会被静默忽略，拼错的键不会报错；延迟字段是 txnLatency.gatewayLatency，不是 latency；
当请求携带 errorInfo 且命中网关状态映射（GSM）规则时，响应还会附加 gsm_info 对象；
不要在 NTW_BASED_ROUTING 之后调用本端点来“记录”所选借记卡组——借记审计来自 /decide-gateway 的 analytics 事件；且应在授权完成后调用，而非之前。

路由规则与规则配置端点

POST /routing/create：创建 Euclid 声明式路由规则

端点页声明（createRoutingRule.mdx）明确其支持四类算法类型：

算法类型	语义
`advanced`	完整 Euclid DSL 规则树
`priority`	有序网关优先级列表
`single`	固定网关
`volume_split`	按比例分配流量

advanced 类型的完整规则语法（AND / OR / 嵌套 AND+OR、volume_split_priority、枚举数组、数值数组匹配等）在 routing-advanced-example.mdx 中有详细示例。典型工作流为：/routing/create 创建 → /routing/activate 激活 → /routing/evaluate 预览评估 → 需要回滚时 /routing/deactivate 停用，全程用 /routing/list/{created_by} 与 /routing/list/active/{created_by} 观察状态。

Rule Configuration 与 Config

/rule/create、/rule/get、/rule/update、/rule/delete 构成服务级 SR / elimination（停机剔除）配置的 CRUD 面；GET /config/routing-keys 返回可用的路由键与维度元数据，POST /config-sr-dimension 用于配置 SR 维度。这两组端点为 /decide-gateway 的 eliminationEnabled 与多维度打分提供配置来源，与 scoring-config 指南页配合使用。

兼容路由与本地冒烟测试

为兼容旧集成，spec 中保留了两条 Legacy 路由：

POST /decision_gateway（legacyDecisionGateway）——旧版决策路由，新集成应改用 /decide-gateway；
POST /update-score（legacyUpdateScore）——旧版打分反馈路由，新集成应改用 /update-gateway-score。

本地与沙箱的完整冒烟测试示例（健康检查、商户创建、决策、反馈、analytics 读取）收录在 API Examples 指南中；本地启动与验证步骤（Docker Compose profile、make 目标、curl http://localhost:8080/health 验证）见 Local Setup。

小结：如何高效使用这套 Schema 参考

查流程看 API Guide（按“建商户 → 建 API key → 配路由 → 跑交易 → 反馈 → 看 analytics”的顺序组织）；
查精确 Schema 落到本文覆盖的端点家族页面，或直接查权威契约 decision_engine_openapi-specs.json（每个端点页的文件头 openapi 字段即为其在 spec 中的 operation 定位）；
鉴权上记住四类访问边界，特别注意 analytics 路由必填 x-tenant-id、沙箱路由必填 x-feature: decision-engine；
需要本地验证时，用 local-setup.md 中的 Docker Compose 或源码构建方式拉起服务，以 GET /health 作为就绪信号。