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

除公开文档和健康检查外，所有 /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)
)复制

GET 请求的原始请求体为空字节数组，其 SHA-256 固定为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。JSON 请求必须针对实际发送的 UTF-8 原始字节签名，禁止重新排序字段后再计算。

幂等范围是“商户 + 操作类型 + 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": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "shopper_email": "[email protected]",
    "card": "CARD_NUMBER",
    "expiration_year": "2029",
    "expiration_month": "08",
    "security_code": "CVV"
  }
}复制

当前仅开放 Elanlink 直连 CARD。first_name、last_name、shopper_email、card、expiration_year、expiration_month 和 security_code 为必填直连字段。网关不会向上游传递 payment_method。

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

当前 Elanlink 仅开放直连，不返回 FORM_POST 或 IFRAME 托管页动作；若直连 3DS 返回 nextAction，必须按原值执行，不得修改或自行补签上游参数。

{
  "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": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "card": "CARD_NUMBER",
    "expiration_year": "2029",
    "expiration_month": "08",
    "security_code": "CVV"
  }
}复制

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

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

资金流水由支付、退款、代付或人工调整产生，只读返回。金额均为分制整数并携带币种；不同币种不得直接汇总。

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

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

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

{
  "eventId": "evt_...",
  "merchantId": 10001,
  "eventType": "payment.succeeded",
  "aggregateType": "PAYMENT",
  "aggregateId": "P...",
  "aggregateVersion": 2,
  "data": {
    "paymentNo": "P...",
    "status": "SUCCEEDED",
    "amount": 1234,
    "currency": "USD"
  },
  "occurredAt": "2026-08-20 13:00:00"
}复制

signedText = X-Gateway-Timestamp + "." + rawRequestBody
expected = "v1=" + lowercase_hex(
  HMAC_SHA256(webhookSecret, signedText)
)复制

验签必须使用收到的 UTF-8 原始请求体。首次失败后依次延迟 1、5、15、30、60、360、1440 分钟重试，总计最多投递 8 次。