获取可用支付通道

按客户地区、币种、金额查询当前可用的支付通道列表。可与 失败后重新建单 配合，在人工干预换通道时避开本组已用过的通道。

GET {BASE_URL}/api/v1/open/payment-gateways

---

请求

查询接口。鉴权方式与查单相同。商户维度限流独立于查单（约 300 次/分钟），IP 维度与查询档共享（约 120 次/分钟）。

请求头

头	必填	说明
Authorization	是	Bearer + 完整 API 密钥

查询参数

参数	类型	必填	说明
region	string	未传 retry_of 时必填	客户地区，大写 ISO 3166-1 alpha-2（如 US）
currency	string	未传 retry_of 时必填	货币代码
amount	number	未传 retry_of 时必填	金额，须 > 0
retry_of	string (uuid)	否	前序支付单的 order.id。传入后 region / currency / amount 从该单继承，可省略

传了 retry_of 时若再显式传入 region / currency / amount，必须与原单一致，否则返回 400。

# 按参数取列表
curl -sS "{BASE_URL}/api/v1/open/payment-gateways?region=US&currency=USD&amount=100" \
  -H "Authorization: Bearer sk.YOUR_MERCHANT.YOUR_SECRET"

# 按失败订单继承参数，并标注本组已用通道
curl -sS "{BASE_URL}/api/v1/open/payment-gateways?retry_of=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -H "Authorization: Bearer sk.YOUR_MERCHANT.YOUR_SECRET"

---

成功响应

200 OK。无可用通道时仍返回 200，gateways 为空数组。

{
  "merchant_checkout_version": "V2",
  "query": { "region": "US", "currency": "USD", "amount": 100 },
  "gateways": [
    {
      "gateway_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "支付通道CA-US",
      "checkout_host": "pay.example.com",
      "methods": [
        { "display_name": "Visa/Mastercard", "payment_type": "ONLINE" }
      ]
    }
  ],
  "note": "指定 gateway_id 创建的订单按 V1 收银台建单，收银页为 /pay/{charge_code}"
}

字段	说明
merchant_checkout_version	商户当前收银台版本（V1 / V2）。指定通道创单时该笔订单仍按 V1 建单
query	实际用于筛选的地区、币种、金额
gateways[].gateway_id	通道 ID，创建收款单时作为 gateway_id 传入
gateways[].name	通道展示名
gateways[].checkout_host	该通道对应的收银域名；无则为 null
gateways[].methods	方式展示名与收款类型（ONLINE 等）
note	指定通道创单的收银台说明

传入 retry_of 时额外返回：

{
  "retry_context": {
    "retry_of": "aaaaaaaa-…",
    "retry_group_id": "bbbbbbbb-…",
    "retry_seq": 1,
    "used_gateway_count": 1
  },
  "gateways": [
    {
      "gateway_id": "…",
      "name": "…",
      "checkout_host": "…",
      "methods": [],
      "used_in_retry_group": true,
      "shares_account_with_retry_group": true
    }
  ]
}

字段	说明
retry_context	本重试组摘要
used_in_retry_group	本组是否已用过该通道
shares_account_with_retry_group	该通道绑定的收款账号是否与本组已用账号相同。true 时用该 gateway_id 创单会被 422 拒绝（换通道等于没换账号）

未固定到具体收款账号的绑定无法判定相交，对应通道的 shares_account_with_retry_group 为 false（不误伤）。列表标注而不剔除已用通道，是否选用由你决定。

---

配合失败重试使用

推荐顺序：

1. 查询是否值得重试
2. 本接口带 retry_of 查看可选通道
3. 创建收款单 同时传 retry_of、gateway_id 和新的 merchant_order_id
4. 停止分发旧 payment_url

---

常见错误

HTTP	说明
400	未传 retry_of 时缺少 region / currency / amount；或这些参数与 retry_of 指向的订单不一致
401	鉴权失败
404	retry_of 指向的订单不存在或不属于当前商户
429	限流

---

注意事项

1. 列表是时点快照，账号日额度/健康度随时变化。创单时若返回 422，请重新拉取本列表后再指定通道。
2. 指定 gateway_id 创建的订单按 V1 收银台建单，收银页为 /pay/{charge_code}，收银域名可能与平时不同。
3. gateway_id 与 payment_methods 互斥，不可同时出现在创建收款单请求体中。
4. 建议对列表结果缓存 ≥30 秒，避免与查单接口共同触发限流。