支付交易网关 API v1

下载 OpenAPI 3.1.1 JSON · 可导入支持OpenAPI的开发工具。此页无需外部资源。

服务端调用需携带 Authorization: Bearer <SERVICE_TOKEN>。令牌不得交给浏览器。协议目录返回字段定义与当前实例可用状态，不返回商户密钥。

接口目录

请求	说明
GET /v1/protocols	协议、通道、配置与下单参数定义（包含未启用的实现）
GET /v1/channels	实现的通道及实例可用状态
GET /v1/protocols/{protocol_id}	获取单一协议及其通道定义
GET /v1/capabilities	当前实例已配置的通道（兼容接口）
POST /v1/payments	幂等创建支付，返回收银台及可用的调起参数
GET /v1/payments/{id}	查询本地支付状态
GET /v1/payments/by-reference/{reference}	按业务充值UUID查询
GET /v1/payments/{id}/events	查询支付与计费结果时间线
GET /v1/payments/{id}/evidence	查询时间线和到账证据
POST /v1/payments/{id}/prepare	原单恢复预支付参数，不创建新交易
GET /openapi.json	下载OpenAPI规范
GET /docs	阅读接口说明
POST /callbacks/payram	PayRam HMAC-SHA256入金通知（仅验签后主动核对原单）
GET /callbacks/epay_legacy	易支付签名异步通知
POST /callbacks/wechat_v3/{reference}	微信v3签名头及AES-GCM通知
POST /callbacks/alipay_rsa2	支付宝RSA2异步通知
GET /returns/epay_legacy	公共支付流程 /returns/epay_legacy
GET /returns/alipay_rsa2	公共支付流程 /returns/alipay_rsa2
GET /checkout/{token}	公共支付流程 /checkout/{token}
GET /checkout/{token}/status	公共支付流程 /checkout/{token}/status
GET /checkout/{token}/qr.svg	公共支付流程 /checkout/{token}/qr.svg
POST /checkout/{token}/prepare	公共支付流程 /checkout/{token}/prepare
GET /livez	公共支付流程 /livez
GET /readyz	公共支付流程 /readyz
GET /assets/checkout.js	公共支付流程 /assets/checkout.js
POST /v1/payments/{id}/upstream/create	易支付API下单（不代表到账；同单成功结果复用）
POST /v1/payments/{id}/upstream/query	易支付主动查询上游订单；验证到账后才更新本地状态

集成步骤

GET /v1/protocols 获取协议、通道、配置字段Schema。GET /v1/channels 获取所有已实现通道及 available。
按 configuration_schema 生成商户表单，writeOnly / x-storage=credentials 字段使用密码控件。payment_request_schema 定义下单时的运行参数，不应存为商户配置。
POST /v1/payments，account_id与external_id必须且只能提供一个；external_id先按application_id和已持久化充值单向计费中心解析。Idempotency-Key 必须与 recharge_order_id 的UUID字符串相同。易支付payment_mode=api且提供client_ip时，网关通过mapi.php下单，payment.payment_url直接返回上游HTTPS payurl；省略模式仍返回前台收银台。next_action（如果有）用于业务SDK或二维码。
查询本地支付状态，或接收预配置的计费回调/消息。同步返回、SDK返回、收银台过期不能证明到账。
核验到账后，计费中心审批并在一个事务中入账；支付网关不直接写钱包。

商户参数统一保存在计费中心。网关支付时通过鉴权配置API读取绑定版本，历史回调与重试使用原版本。available表示适配代码可用，实际下单还需要计费中心启用有效的商户配置。接口只向已授信服务开放，不支持匿名调用、多租户隔离或任意回调地址。

创建示例

curl -X POST "$GATEWAY/v1/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 11111111-1111-4111-8111-111111111111" \
  -H "Content-Type: application/json" \
  --data @payment.json

{
  "recharge_order_id": "11111111-1111-4111-8111-111111111111",
  "application_id": "22222222-2222-4222-8222-222222222222",
  "account_id": "33333333-3333-4333-8333-333333333333",
  "external_order_id": "order-001",
  "currency": "CNY",
  "amount_decimal": "12.34",
  "channel": "alipay_page",
  "callback_url": "https://billing.example.invalid/api/internal/payment-center/events",
  "confirmation_mode": "manual"
}

账户标识二选一：传account_id UUID，或删除account_id并传external_id字符串（例如customer-001）。未选字段可省略或为null。两者同时为非空或均缺失会拒绝。external_id须属于application_id且与已有recharge_order_id绑定账户一致。解析后按内部UUID计算幂等指纹和记录事件；两种写法定位同一账户时重试返回原支付。

通用下单参数

参数	约束
recharge_order_id	必填；uuid
application_id	必填；uuid
account_id	选填；与external_id二选一；计费中心内部账户UUID。
external_id	选填；与account_id二选一；须属于application_id及已有充值单，1–128字节，无首尾空白或控制字符。
external_order_id	必填；string
currency	必填；string
amount_decimal	必填；以元为单位的正十进制字符串，最多2位小数；业务还会校验正值与金额上限。
channel	必填；string
network	选填；null
callback_url	必填；必须等于网关预配置的计费回调地址，不能指定任意地址。
confirmation_mode	必填；支付确认策略；不代替计费中心资金审批。
exchange_snapshot	选填；可选金额快照；官方通道仅支持CNY且不能换汇。
payer_openid	选填；null
alipay_buyer_id	选填；null
alipay_buyer_open_id	选填；null

易支付旧版 / epay_legacy

配置模式：billing_center。配置Schema的required表示计费中心商户配置表单要求；不代表需要在每笔支付传入这些字段。

配置键	定义
base_url	上游服务地址；上游地址；配置由计费中心持有
merchant_id	商户ID；配置项；配置由计费中心持有
merchant_key	商户密钥；加密凭证；配置由计费中心持有

通道	下单特有参数 / 调起方式
alipay	支付宝（易支付）；redirect
wechat	微信（易支付）；redirect
epay_usdt	USDT（易支付，人民币报价）；redirect

微信支付官方 API v3 / wechat_v3

配置模式：billing_center。配置Schema的required表示计费中心商户配置表单要求；不代表需要在每笔支付传入这些字段。

配置键	定义
base_url	上游服务地址；上游地址；配置由计费中心持有
merchant_id	微信商户号；配置项；配置由计费中心持有
cert_serial	商户证书序列号；配置项；配置由计费中心持有
private_key_pem	商户私钥PEM；加密凭证；配置由计费中心持有
api_v3_key	API v3密钥；加密凭证；配置由计费中心持有
public_keys	微信支付公钥映射JSON；加密凭证；配置由计费中心持有
public_key_id	当前微信支付公钥ID；配置项；配置由计费中心持有
jsapi_app_id	公众号AppID；配置项；配置由计费中心持有
mini_app_id	小程序AppID；配置项；配置由计费中心持有
native_app_id	扫码支付AppID；配置项；配置由计费中心持有

通道	下单特有参数 / 调起方式
wechat_native	微信扫码支付；qr_code
wechat_jsapi	微信内支付；payer_openid必填；wechat_jsapi
wechat_mini_program	微信小程序支付；payer_openid必填；wechat_mini_program

支付宝官方 RSA2 / alipay_rsa2

配置模式：billing_center。配置Schema的required表示计费中心商户配置表单要求；不代表需要在每笔支付传入这些字段。

配置键	定义
base_url	上游服务地址；上游地址；配置由计费中心持有
app_id	支付宝应用AppID；配置项；配置由计费中心持有
merchant_id	支付宝收款商户ID；配置项；配置由计费中心持有
private_key_pem	应用私钥PEM；加密凭证；配置由计费中心持有
public_key_pem	支付宝公钥PEM；加密凭证；配置由计费中心持有

通道	下单特有参数 / 调起方式
alipay_page	支付宝电脑网站支付；redirect
alipay_wap	支付宝手机网站支付；redirect
alipay_qr	支付宝扫码支付；qr_code
alipay_mini_program	支付宝小程序支付；alipay_buyer_id与alipay_buyer_open_id二选一；alipay_mini_program

PayRam（USD 稳定币） / payram

配置模式：billing_center。配置Schema的required表示计费中心商户配置表单要求；不代表需要在每笔支付传入这些字段。

配置键	定义
base_url	上游服务地址；上游地址；配置由计费中心持有
project_id	PayRam项目标识（审计用）；配置项；配置由计费中心持有
api_key	项目API Key；加密凭证；配置由计费中心持有

通道	下单特有参数 / 调起方式
usdt	USDT（PayRam，美元报价）；redirect

epay_usdt映射易支付type=usdt；money及回调money仍为CNY报价、最多两位小数。网关不推算USDT数量或网络，也不将上游交易号作为链上哈希。实际USDT付款信息以上游收银台为准。

响应与事件

Observation包含payment_id、version、event_id、status（pending/succeeded）、payment和可选verification。next_action类型为qr_code、wechat_jsapi、wechat_mini_program、alipay_mini_program。redirect通过payment_url前往收银台。创建返回pending时，预支付可能仍待恢复，应按原单查询。

HTTP回调携带Observation，Payment-Timestamp与Payment-Signature: v1=<hex>采用HMAC-SHA256(secret, timestamp + "." + 原始body)，校验300秒时间窗口。响应2xx后网关标记HTTP投递成功；事件按event_id及version去重。NATS的payment.events.v1携带事件信封，与HTTP共用身份，具体信封和JetStream约定参见仓库billing-integration.md。付款确认不会自动审批或改变钱包余额。

错误与重试

401鉴权失败；400参数错误；404未找到；409幂等/交易身份冲突；503依赖暂不可用。框架校验也可能返回413、415或422和纯文本。503或超时后使用相同UUID查询或重试，禁止生成新单绕过不确定状态。网关不支持退款、主动关单、服务商代调用或结算对账。