聚合支付网关
商户接入文档

除公开文档和健康检查外，所有 /gateway/v1/** 请求均须携带下列请求头。API Secret 只在后台生成时显示一次。

签名原文

UPPERCASE_HTTP_METHOD + "\n" +
requestTarget + "\n" +
timestamp + "\n" +
nonce + "\n" +
lowercase_hex_sha256(rawBody)复制

requestTarget 是原始路径与原始查询字符串，例如 /gateway/v1/payments?page=1&pageSize=50。查询参数顺序和编码必须与实际发送的 URL 完全一致。

signature = "v1=" + lowercase_hex(
  HMAC_SHA256(apiSecret, canonicalText)
)复制

幂等范围是“商户 + 操作类型 + Idempotency-Key”。相同 Key 和相同请求返回首次结果；请求内容不同返回 1004。

{
  "code": 1,
  "message": "Success",
  "data": {},
  "requestId": "req_..."
}复制

• code=1 表示接口处理成功。
• 错误响应的 data 为 null。
• 请求体最大 1 MB，超出返回 HTTP 413 / 1007。
• 只支持 ISO 默认精度为两位小数的币种；金额按分传整数，例如 12.34 传 1234。

{
  "merchantOrderNo": "ORDER-20260820-001",
  "currency": "USD",
  "amount": 1234,
  "paymentMethod": "CARD",
  "channelSelectionMode": "AUTO",
  "country": "US",
  "returnUrl": "https://merchant.example.com/payment/return",
  "notifyUrl": "https://merchant.example.com/api/payment/notify",
  "metadata": {"customerReference": "C10001"}
}复制

channelSelectionMode 支持 AUTO、PREFERRED、STRICT。PREFERRED/STRICT 必须提供后台分配的稳定 channelCode。

当响应包含 nextAction 时，按其 type 执行 REDIRECT、FORM_POST 或 IFRAME；不得修改或自行补签上游参数。

{
  "merchantRefundNo": "REFUND-20260820-001",
  "amount": 500,
  "reason": "Customer request"
}复制

退款固定使用原支付渠道账户。支付订单的累计成功退款与处理中退款不得超过可退款金额。

{
  "merchantSubscriptionNo": "SUB-20260820-001",
  "customerReference": "C10001",
  "customerEmail": "[email protected]",
  "currency": "USD",
  "planCode": "MONTHLY_STANDARD",
  "paymentMethod": "CARD",
  "notifyUrl": "https://merchant.example.com/api/subscription/notify",
  "paymentMethodData": {}
}复制

金额、周期数量和周期单位由后台订阅包价格决定，商户请求不能覆盖。失败扣款同样生成完整周期账单。

收款明细由渠道能力决定；完整收款资料只用于向上游发起请求，加密保存且不在查询接口返回。

每天 01:00（Asia/Shanghai）生成前一日数据；即使没有交易也会生成空报表。下载接口不接受临时维度筛选。

网关在本地订单结果被同步响应、上游订单级异步回调或主动查询确认后，向订单级 notifyUrl 与商户级通知地址分别投递。每个目标独立重试。

商户回调响应体去除首尾空白后必须精确等于 SUCCESS，否则视为失败并进入延迟重试。不要仅依赖 HTTP 状态码。

{
  "eventId": "evt_...",
  "eventType": "payment.succeeded",
  "businessNo": "P...",
  "occurredAt": "2026-08-20T13:00:00+08:00",
  "data": {
    "paymentNo": "P...",
    "status": "SUCCEEDED",
    "amount": 1234,
    "currency": "USD"
  }
}复制

通知按商户 Webhook Secret 使用 HMAC-SHA256 签名；验签应针对收到的原始请求体。具体通知请求头以商户后台当前配置页显示为准。