API 参考：支付与退款

日期： 2026-09-18

状态： 已发布；字段级契约以自动生成 OpenAPI 为准

1. 已发布服务端接口

POST /open/v1/checkout-sessions
GET  /open/v1/checkout-sessions/{sessionId}
POST /open/v1/terminal-payments
POST /open/v1/refunds
GET  /open/v1/refunds/{refundId}

除门店收银终端使用的微信付款码接口外，当前没有其他独立创建支付、查询支付、关闭支付或查询支付方式的公共路径。客户通过支付会话创建订单，并通过会话查询获得关联的 orderId 和 orderStatus。

2. 创建支付会话

请求字段包括 outTradeNo、merchantId、scene、amountFen、currency 和 subject。可选字段包括 storeId、paymentProductCodes、returnUrl、allocationIntent 和 metadata。channelCode 仅为兼容旧接入保留，新接入应使用产品白名单并由平台路由。

• amountFen 使用人民币整数分。
• scene 为 MINI_PROGRAM、APP、H5、PC 或 QRCODE。
• merchantId、可选 storeId、应用和渠道绑定都必须位于当前租户与应用授权范围内。
• returnUrl 必须是已登记在当前应用白名单中的 HTTPS 协议、域名和端口；回跳不代表支付成功。
• allocationIntent 是结构化配置快照，不代表分账执行 API 已发布。只有已签约产品和渠道明确支持时才可使用。
• 会话固定有效 30 分钟，不能由客户请求改变。
• 传入 paymentProductCodes 时，会话先返回 CREATED、paymentMethods 与 selectionRequired=true，此时尚未创建支付订单；付款人在托管收银台完成选择后才会创建唯一订单。

响应中的 action.type 与场景对应：MINI_PROGRAM_LAUNCH、APP_H5、H5_URL、PC_H5 或 QRCODE_URL。客户端只处理当前响应给出的动作，不应假设某支付产品一定支持所有场景。

3. 托管收银台

付款人页面使用 GET /checkout/{sessionId}，状态轮询由页面调用 GET /checkout/{sessionId}/status。支付方式可通过 GET /checkout/{sessionId}/methods 查询，并通过 POST /checkout/{sessionId}/method-selection 提交不透明 optionId。这些入口凭不可猜测会话号访问，不使用应用 HMAC；只能返回付款人所需的脱敏字段，绝不返回内部 channelCode、渠道商户号或凭证。

4. 门店终端微信付款码

POST /open/v1/terminal-payments 仅用于收银员扫描付款人微信付款码的线下场景，固定路由到 JeePay 聚合支付的 WX_BAR 方式。

• 应用必须授予 TERMINAL_PAYMENT_CREATE，并且商户、门店、终端及生产产品资格均处于启用状态。
• authCode 必须为扫码当下获得的 18 位付款码；它是一次性敏感值，不得写入业务日志、数据库、元数据、客户响应或异步重试队列。
• 平台同时校验终端必须归属所传门店、商户和租户；数据库也执行同样的边界约束。
• 正常受理返回 ACCEPTED；通道响应不确定或返回了不应有的客户端拉起动作时返回 UNKNOWN，必须查询原订单，不得换单号重试。

5. 支付状态

服务端使用 GET /open/v1/checkout-sessions/{sessionId} 查询会话与订单状态。前端跳转、二维码扫描或客户端 SDK 结果只能触发反查，不能直接把订单置为成功。

支付终态以签名查询结果或已验签 Webhook 为准。UNKNOWN 表示结果待收敛，必须继续查询原单，不能新建订单规避。

6. 退款

退款请求字段为 outRefundNo、orderId、amountFen 和可选 reason。只允许对成功订单退款；累计金额不得超过原单，支付后 180 天内最多 50 次，相邻退款至少间隔 1 分钟。

退款写操作强制 Idempotency-Key。PROCESSING 或 UNKNOWN 不是失败终态；应查询原退款号或等待 Webhook，不得更换退款单号重复提交。

7. 契约来源

完整字段、响应结构和错误状态见 自动生成 OpenAPI。手写说明与自动生成契约冲突时，以当前部署版本的 OpenAPI 和运行网关为准。