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

除公开文档和健康检查外，所有 /gateway/v1/** 请求均须携带下列四个鉴权头。API Secret 由商户在商户后台自行创建、查看和切换；切换后旧 Secret 继续有效 10 分钟。

Idempotency-Key 不是全局鉴权头，只在创建支付、退款、代付、订阅和取消订阅等写接口中必传，最长 128 字符。带 JSON 请求体时使用标准 Content-Type: application/json；查询与下载接口不需要幂等头。

开户后取得 Merchant ID 和商户后台账号。登录商户后台后自行创建 API Secret 和 Webhook Secret；Merchant ID 用于定位当前启用的 API Secret，API Secret 用于请求签名，Webhook 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": 200,
  "message": "Success",
  "data": {},
  "requestId": "req_..."
}复制

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

第一层响应码

使用后台绑定的渠道支付参数创建支付。请求必须携带签名请求头和 Idempotency-Key。金额只接受整数分，商户订单号在当前商户范围内必须唯一。直连卡资料与收银台资料二选一，不允许商户指定渠道。

请求字段

paymentMethodData 字段

请求示例

{
  "merchantOrderNo": "ORDER-20260820-001",
  "currency": "USD",
  "amount": 1234,
  "paymentMethod": "CARD",
  "customerEmail": "ada\u0040example.com",
  "notifyUrl": "https://merchant.example.com/api/payment/notify",
  "returnUrl": "https://merchant.example.com/payment/return",
  "paymentMethodData": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "cardNumber": "CARD_NUMBER",
    "expirationYear": "2029",
    "expirationMonth": "08",
    "securityCode": "CVV",
    "billingCountry": "US"
  }
}复制

当前仅开放 Elanlink 直连 CARD。下游只提交网关统一字段；渠道字段名、渠道商户号、渠道通知地址、签名、token_flag 和其他渠道常量均由网关生成。网关不会向上游传递 payment_method。

当前支付方式与渠道支付参数由超级后台一对一绑定。下游不能指定渠道，也不能提交 channelCode 或 channelSelectionMode。

创建支付与支付查询响应字段

按平台订单号、商户订单号查询及支付列表中的每个订单使用同一字段结构。订阅订单的 subscriptionCycleNo 对应通知的 data.cycleNo；失败期也可查，订阅期链接口按真实期数正序返回，不因失败中断。

创建支付响应示例

{
  "code": 200,
  "message": "Success",
  "data": {
    "paymentNo": "P84000000000000001",
    "merchantOrderNo": "ORDER-20260820-001",
    "amount": 1234,
    "feeAmount": 20,
    "netAmount": 1214,
    "currency": "USD",
    "paymentMethod": "CARD",
    "status": 3,
    "refundState": 20,
    "refundedAmount": 0,
    "channelCode": "ELANLINK",
    "providerCode": "ELANLINK",
    "providerTransactionId": null,
    "failureCode": null,
    "failureMessage": null,
    "failureSolution": null,
    "resultSource": 4,
    "notificationStatus": 1,
    "issueUrl": null,
    "nextAction": {
      "type": 1,
      "url": null,
      "parameters": {}
    },
    "aggregateVersion": 1,
    "createdAt": "2026-08-21 15:30:00",
    "paidAt": null
  },
  "requestId": "req_..."
}复制

支付列表查询参数

当前 Elanlink 仅开放直连，不返回 FORM_POST 或 IFRAME 托管页动作。HTTP 成功且同步响应包含非空 issuer_url 时，创建结果为 3（处理中），在 data 内同时返回 issueUrl 和 THREE_DS nextAction，两处地址完全一致。浏览器直接 GET 打开，不构造 POST 表单。nextAction 保留 type、url、parameters，不再输出 method；后续支付结果仍只由渠道异步通知或平台主动查单确认，地址字段不参与状态迁移。

3DS 过渡响应字段示例（data 内，非完整订单）

{
  "issueUrl": "https://issuer.example/3ds?order_no=P...",
  "nextAction": {
    "type": 7,
    "url": "https://issuer.example/3ds?order_no=P...",
    "parameters": {}
  }
}复制

以上地址仅为格式示例。实际返回地址中的 notify_url、return_url 等参数必须完整保留；没有传 returnUrl 的商户可自行补充 return_url。浏览器返回页不代表支付成功。

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

退款必须引用当前商户的真实原支付订单，固定使用原支付保存的渠道支付参数 ID 与配置版本；支付参数停用后禁止新退款。退款收费和渠道成本在本次退款创建时固化，预占本金加手续费。累计成功退款与处理中退款本金不得超过可退款金额。

退款响应字段

创建和详情返回 data 对象；列表返回同结构的 data 数组。金额均为整数分，时间为东八区 yyyy-MM-dd HH:mm:ss。

创建上游管理的自动续订。请求必须携带签名请求头和 Idempotency-Key。平台不维护商品、订阅包或价格版本；商户在每次创建时实时提交金额和周期条款。

请求字段

paymentMethodData 字段

请求示例

{
  "merchantOrderNo": "ORDER-20260820-001",
  "customerEmail": "customer\u0040example.com",
  "currency": "USD",
  "amount": 999,
  "recurringAmount": 2999,
  "pricingMode": 2,
  "discountCycles": 3,
  "planCode": "MONTH",
  "intervalCount": 1,
  "totalCycles": 0,
  "paymentMethod": "CARD",
  "notifyUrl": "https://merchant.example.com/api/subscription/notify",
  "returnUrl": "https://merchant.example.com/subscription/return",
  "paymentMethodData": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "cardNumber": "CARD_NUMBER",
    "expirationYear": "2029",
    "expirationMonth": "08",
    "securityCode": "CVV",
    "billingCountry": "US"
  }
}复制

当前订阅只走直连。Elanlink 接受 DAY、WEEK、MONTH、YEAR；平台映射为上游 interval，并将 totalCycles 映射为 billing_cycle。首期优惠时，上游外层 amount 使用优惠期实扣金额，订阅字符串中的 contract_amount 使用优惠结束后的标准金额，discountCycles 映射为 promotion_cycle。预售时 contractStart 映射为上游 contract_start；它是独立条款，因此可与首期优惠同时提交。Elanlink 要求的 shopper_id 由网关使用规范化后的 customerEmail 生成。首期和每次续期都是独立正式支付订单；优惠期内沿用冻结的优惠金额，超过优惠期后使用冻结的标准金额。

创建订阅同步响应

subscriptionNo 在请求校验通过、首期支付订单落库时预生成，早于上游调用，不依赖渠道订阅 ID。订单已创建后，无论同步支付状态为处理中或失败，都保留并返回这个编号；同一幂等请求重放返回原编号，不重复生成。首订成功和各期续订通知均使用同一个 subscriptionNo，期数由 cycleNo 区分。校验失败且未创建订单时，不返回订阅号。

同步响应使用标准支付对象，只表示首期正式支付订单的当前状态。平台在创建首期支付订单时生成唯一 subscriptionNo，保存到支付订单并同步返回；该编号只用于结果关联，不表示订阅已经生效。只有上游异步通知或主动查单明确确认首期成功后，平台才创建订阅管理数据，并通过 subscription.activated 异步通知确认生效。上游同步成功响应不能直接激活订阅。

创建订阅响应示例

{
  "code": 200,
  "message": "Success",
  "data": {
    "paymentNo": "P84000000000000003",
    "merchantOrderNo": "ORDER-20260820-001",
    "orderInitiator": 1,
    "subscriptionNo": "8c8de29c90ac4866b2067cb442b6f229",
    "amount": 2999,
    "feeAmount": 0,
    "netAmount": 2999,
    "currency": "USD",
    "paymentMethod": "CARD",
    "status": 3,
    "providerCode": "ELANLINK",
    "providerTransactionId": null,
    "issueUrl": null,
    "nextAction": {
      "type": 1,
      "url": null,
      "parameters": {}
    },
    "resultSource": 4,
    "createdAt": "2026-08-21 15:30:00"
  },
  "requestId": "req_..."
}复制

订阅查询参数

订阅关系与扣费结果分开：续存中 renewalStatus=9 的订阅保持 effectiveStatus=9，单期扣费失败不会取消或终止订阅，也不代表失败期已支付。取消或自然完成后，才按实际已支付账期的开始和结束判断生效状态。

当期扣费结果（订阅管理响应）

“当期”是已存在的最大明确期数，不按当前时间预测下一期。没有新一期通知就保持原结果；失败不重试扣款，历史失败订单完整保留。

支付链接口返回该订阅的每一期正式支付订单，包括扣款失败的期数。subscriptionCycleNo 是上游明确提供的真实期数，缺失时网关不会猜测或补造。续订必须先找到精确上一期；上一期缺失时异步重试，不跳期处理。

平台账期从首期明确支付成功开始计时。每期订单保存 subscriptionPeriodStart（含）与 subscriptionPeriodEnd（不含），下一期开始等于上一期结束；月和年始终以首期日期为锚点，避免月底漂移。失败续订仍有账期，但不延长已支付有效期；通知迟到或重复不会移动账期。首期未成功和普通支付的这两个字段为空。账期由平台管理，不代表渠道返回的扣款排程。

订阅支付订单字段

请求字段

请求须携带商户签名和 Idempotency-Key。使用后台绑定的唯一代付参数；商户不能指定渠道。支付方式和收款资料须满足已启用渠道能力。

提交前原子预占本金加手续费。币种账户缺失时按零余额进入建账流程；余额不足则回滚，不发起上游代付。成功扣减冻结资金，明确失败、取消或关闭释放；未知结果保持冻结并查单确认。

代付响应字段

创建和详情返回 data 对象；列表返回同结构的 data 数组。金额均为整数分，时间为东八区 yyyy-MM-dd HH:mm:ss。

资金流水由支付、退款、代付或人工调整产生，只读返回。每条包含 entryNo、businessType、businessNo、entryType、有符号整数分 changeAmount、currency 和 occurredAt。接口只返回当前已认证商户自己的资金流水；渠道支付参数余额及其变化记录属于内部运营数据，不通过商户 API 暴露。不同币种不得直接汇总。

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

列表可传 from、to（yyyy-MM-dd）、status、page、pageSize，默认第 1 页、每页 20 条，最多 200 条。成功响应 data 为 {items, page, pageSize, total}，不是直接返回数组。

只有支付或订阅扣款明确成功后才投递。请求提供 notifyUrl 时只使用该地址；未提供时回退商户默认 Webhook；两者都没有则交易创建失败。处理中、需要客户端动作、失败和未知结果都不产生下游支付状态通知。

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

首期订阅成功事件类型为 subscription.activated，其 data 携带创建响应中已经返回的平台 subscriptionNo、首期 paymentNo 和 cycleNo=1，用于确认该订阅已经生效；续订成功事件为 subscription.renewed。两类成功事件的 data 还包含 subscriptionPeriodStart、subscriptionPeriodEnd，与对应订单查询结果一致。失败期保留在查询链中但不投递失败通知。

订阅支付通知字段（首订与续订相同）

上述业务时间统一使用东八区 yyyy-MM-dd HH:mm:ss。以下为第 2 期成功通知的格式示例，并非真实交易记录。既有历史事件保留原始内容；新增字段不会通过重发补写到历史报文。

{
  "eventId": "evt_example_subscription_cycle",
  "merchantId": "83946179674509312",
  "eventType": "subscription.renewed",
  "aggregateType": "PAYMENT",
  "aggregateId": "P12345678901234567",
  "aggregateVersion": 2,
  "data": {
    "subscriptionNo": "0123456789abcdef0123456789abcdef",
    "paymentNo": "P12345678901234567",
    "cycleNo": 2,
    "subscriptionPeriodStart": "2026-08-28 10:00:00",
    "subscriptionPeriodEnd": "2026-08-29 10:00:00",
    "amount": 100,
    "currency": "USD",
    "status": 5,
    "paidAt": "2026-08-28 10:00:03"
  },
  "occurredAt": "2026-08-28 10:00:04"
}复制

单次支付成功通知示例

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

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

Webhook Secret 是商户级单一凭据，不属于某个 URL，也不发送 Secret 版本。商户后台允许保存多条默认地址，但同一时间只启用一条；订单传入 notifyUrl 时仍只投递该订单地址。新增或切换地址不会改变 Secret；商户生成新的 Webhook Secret 后，旧 Secret 继续用于通知签名 10 分钟，随后自动使用新 Secret。

这 10 分钟内不允许再次轮转 Webhook Secret；后台显示剩余时间并禁用轮转操作，服务端也会拒绝并发或绕过页面的再次轮转。请在过渡期结束前部署新 Secret，并在过渡期同时接受新旧签名。该限制不改变 API Secret 的独立凭据有效期规则。

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

平台状态使用同一套全局编号：同一个数字在任何业务中含义完全一致，不需要的编号直接留空。商户 API、Webhook、商户后台和超级后台的内部状态字段统一返回整数编号。英文状态仅作为文档语义名称展示，不作为接口值。0 只可作为查询条件中的“全部/未指定”，永远不是真实业务状态。

各商户 API 字段允许值

code=200 只表示本次 API 请求处理成功。非 200 表示接口处理失败，data 为 null；交易结果仍必须读取业务对象的 status。