支付中台开放接口文档（详细版）

1. 接入概览

1.1 接口清单

1.2 业务流程总览

1. 1接入方 → 平台申请入账方，进入「入账方审核 / 签约」
2. 2平台 → 接入方审核签约通过后获得 recipientId
3. 3接入方 → 平台支付下单（settlementMode=DELAYED）
4. 4平台 → 接入方支付结果回调
5. 5接入方 → 平台发起订单分账 / 余额分账
6. 6平台 → 接入方分账结果回调
7. 7接入方 → 平台需要时发起退款 / 资金归还
8. 8平台 → 接入方退款 / 归还结果回调

1.3 接入准备

1. 向平台申请开通开放 API 应用，平台将发放以下凭证：
   • appId：应用标识；
   • apiSecret：请求签名密钥（≥32 字符）；
   • callbackSecret：回调验签密钥（≥32 字符，仅用于校验平台推送，不参与请求签名）。
2. 将需要操作的商户商编与应用完成绑定（一个应用可绑定多个商户号）。
3. 准备接收异步通知的 HTTPS 地址。

2. 通用约定

2.1 统一响应包络

所有接口（含鉴权失败）返回统一结构：

{ "code": "00000", "msg": "成功", "data": { } }

注意：code=00000 仅代表请求处理成功。支付、退款、分账等异步业务的最终结果以 data.status、异步回调或主动查询为准。

3. 请求签名（鉴权）

所有开放接口均需通过 HMAC-SHA256 签名鉴权。签名不通过时返回 HTTP 401 + code=A0002。

3.1 请求头

3.2 签名算法

第一步：构造规范化串（各段以 \n 连接，共 6 行）：

HTTP_METHOD          ← 大写，如 POST
requestPath          ← 如 /openapi/v1/payments（不含域名、不含 query）
rawQueryString       ← 原样 query 串；无则空字符串
timestamp            ← X-Timestamp 的值
nonce                ← X-Nonce 的值
sha256Hex(body)      ← 请求体原文的 SHA-256 十六进制；GET/无 body 时空串的 SHA-256

第二步：计算签名：

signature = hex( HmacSHA256( canonicalString, apiSecret ) )   ← 小写十六进制

第三步：将签名放入 X-Signature 请求头。

3.3 常见鉴权失败原因

签名注意事项

• rawQueryString 必须与实际请求 URL 完全一致（含编码与顺序），建议先拼签名再拼 URL；
• 请求体必须以原始字节参与 SHA-256，不可重新序列化后再算；
• GET 请求 body 为空，sha256Hex("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855；
• 服务器时间请使用 NTP 校准，避免时间戳过期。

4. 幂等机制

所有资金类写操作（支付下单、退款、订单分账、资金归还、订单分账完结、余额分账）均支持幂等：

• 写接口必须携带请求头 X-Idempotency-Key（建议取业务单号或其摘要），缺失时请求被拒绝；
• 同一幂等键在 24 小时 内重复请求，平台直接返回首次处理结果，不会重复发起资金操作；
• 首次处理失败时幂等键自动释放，修正后可重试；
• 相同幂等键的并发请求会收到「请求处理中」提示，请稍后查询结果。

建议：X-Idempotency-Key 与业务单号保持强关联（例如取 outTradeNo / refundRequestNo / businessNo 的哈希），同一笔业务重试时不得更换。

5. 支付接口

5.1 支付下单

创建支付订单并提交渠道受理。USER_SCAN（扫码）模式返回收银台链接；其余模式返回渠道唤起凭证。

请求体：

paymentMode 取值：

付款码（B 扫 C）等其他产品不在本接口支持范围。

响应 data：

示例请求：

POST /openapi/v1/payments HTTP/1.1
Content-Type: application/json; charset=UTF-8
X-App-Id: app-20260901-001
X-Timestamp: 1760233200
X-Nonce: 8f14e45fceea167a5a36dedd4bea2543
X-Signature: 3f7a1c...（64 位 hex）
X-Idempotency-Key: 9a8b7c6d-pay-0001

{
  "merchantNo": "10080000001",
  "outTradeNo": "ORDER202610120001",
  "amount": 1.00,
  "paymentMethod": "WECHAT",
  "paymentMode": "USER_SCAN",
  "goodsName": "会员充值",
  "userIp": "61.135.169.121",
  "notifyUrl": "https://api.partner.com/callback/payment",
  "settlementMode": "DELAYED"
}

示例响应：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "outTradeNo": "ORDER202610120001",
    "paymentNo": "TR2026101200000001",
    "amount": 1.00,
    "currency": "CNY",
    "status": "PAYING",
    "paymentData": "https://cashier.example.com/pay?merchantNo=10080000001&tn=TR2026101200000001",
    "settlementStatus": null,
    "errorCode": null,
    "errorMessage": null
  }
}

5.2 查询支付订单

响应结构同 5.1 响应。

6. 退款接口

6.1 申请退款

请求体：

同步成功仅代表退款请求已受理，最终以 status、回调或查询为准。

响应 data：

6.2 查询退款

refresh=true（默认）时主动向支付机构同步状态。响应结构同上。

7. 入账方管理接口

入账方（分账接收方）是余额分账的资金接收主体。先申请入账方，审核签约通过后，以 recipientId（入账方申请号）参与余额分账。

7.1 申请入账方

请求体：

响应 data：

7.2 查询入账方申请进度

查询时会先同步渠道最新审核状态再返回。status=COMPLETED 且返回 signUrl 时，入账方完成签约即可用于余额分账。

8. 分账接口

8.1 发起订单分账

对本系统支付接口创建、支付成功（SUCCESS）且未退款的订单发起分账；原收款商户号由平台根据 outTradeNo 自动识别。

⚠️ 前置条件：原订单必须以 settlementMode=DELAYED 创建，并已完成清算。实时结算订单发起会收到渠道 OPR15035 错误（平台已转译为友好提示）。

请求体：

details[] 明细：

响应 data：

8.2 查询订单分账结果

按业务幂等号查询，平台根据回调订阅记录自动识别分账方商户。响应同 8.1。

8.3 申请订单分账资金归还

将已分出的订单分账资金按金额归还给分账方；平台根据 outTradeNo + 分账幂等号自动关联原分账明细。

请求体：

响应 data：businessNo、outTradeNo、status、amount、reason、createdAt、completedAt、errorCode、errorMessage、nextAction。

8.4 查询订单分账资金归还结果

8.5 发起订单分账完结

释放原订单分账后剩余的冻结资金。完结分账使用独立于原分账的请求号，同一订单仅允许完结一次；重复调用时平台幂等回放已受理结果，不会重复完结。

行为说明：

• 前置条件：该订单存在一笔支付成功且分账成功的订单分账，否则报「原订单分账尚未成功，不能发起完结分账」；
• 发起订单分账时若 releaseRemainingAmount=true（分账成功自动解冻剩余金额），则无需再完结；
• 订单分账确认成功后，平台默认会自动发起完结（自动解冻的除外）；自动完结失败或需要指定说明时，可用本接口显式完结；
• 完结没有独立的异步回调：PROCESSING / UNKNOWN 状态请以相同参数重新调用本接口（幂等回放）或查询订单分账结果确认。

请求体：

响应 data：

示例请求：

{ "outTradeNo": "ORDER202610120001", "description": "订单分账完成，释放剩余资金" }

示例响应：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "businessNo": "COMPLETE-ORDER202610120001",
    "outTradeNo": "ORDER202610120001",
    "status": "SUCCESS",
    "releasedAmount": 7.60,
    "createdAt": "2026-10-12 10:30:00",
    "completedAt": "2026-10-12 10:30:01",
    "errorCode": null,
    "errorMessage": null,
    "nextAction": "NONE"
  }
}

8.6 发起余额分账

从分账方易宝资金账户余额中向入账方划拨资金。平台固定使用 accountType=YEEPAY_ACCOUNT、divideVerifyType=STANDARD_DIVIDE、接收方类型 RECEIVER。

请求体：

details[] 明细：

响应 data：结构同 8.1 响应。

幂等与重试：同一 businessNo 重试时若上次状态为 PROCESSING/UNKNOWN 会直接回放本地结果，不会重复划拨；仅上次 FAIL 的记录可沿用原号重试。

8.7 查询余额分账结果

9. 异步回调通知

9.1 事件类型

同一业务状态未变化时不会重复推送；终态事件投递后订阅自动失效。订阅有效期默认 30 天。

9.2 通知报文

POST application/json; charset=UTF-8，body 为下单/发起时登记的 notifyUrl 接收：

{
  "eventId": "3f8a2b6c-....-....",
  "eventType": "payment.status.changed",
  "occurredAt": "2026-10-12T10:05:30.123Z",
  "appId": "app-20260901-001",
  "merchantNo": "10080000001",
  "businessNo": "ORDER202610120001",
  "status": "SUCCESS",
  "data": { }
}

9.3 回调请求头与验签

回调签名验证：

canonical = timestamp + "\n" + nonce + "\n" + eventId + "\n" + sha256Hex(rawBody)
expected  = hex( HmacSHA256( canonical, callbackSecret ) )
校验：expected 与 X-Callback-Signature 小写比较一致

请务必用原始报文字节计算 SHA-256，并用 callbackSecret（不是 apiSecret）验签。

9.4 应答要求

• 收到回调后请先验签、落库，再应答；
• 处理成功：响应 HTTP 2xx 且响应 body 恰为文本 SUCCESS；
• 其余情况（非 2xx 或 body ≠ SUCCESS）平台视为失败进入重试；
• 请保证接口幂等：同一 eventId 可能被重复投递。

9.5 重试策略

9.6 注意事项

• notifyUrl 必须为 HTTPS，不得携带用户信息与 #fragment；
• 同一 businessNo 的回调地址与商户绑定关系创建后不可变更（重复发起时保持一致即可）；
• 回调可能乱序：请以查询接口 refresh=true 的结果为准做最终校准；
• 若长时间未收到回调，主动调用对应查询接口兜底。

10. 状态字典

10.1 支付状态

10.2 结算状态

延迟结算（settlementMode=DELAYED）订单的清算状态，随 payment.settlement.changed 回调或查询接口的 settlementStatus / settlementAmount / unSplitAmount / settlementTime 体现；清算完成是发起订单分账的前提。

10.3 退款状态

10.4 分账状态（订单/余额通用）

details[].status 为单笔明细状态，枚举同上；整单 status 存在任一明细 PROCESSING 即为 PROCESSING，全部 SUCCESS 才为 SUCCESS。

10.5 入账方状态

11. 签名与调用示例

11.1 Node.js 签名与调用

const crypto = require('crypto')

const BASE_URL = 'https://api.your-platform.com'
const APP_ID = 'app-20260901-001'
const API_SECRET = 'your-api-secret-at-least-32-chars'

function sign(method, path, query, bodyStr) {
  const timestamp = String(Math.floor(Date.now() / 1000))
  const nonce = crypto.randomBytes(16).toString('hex')           // 32 位
  const bodySha256 = crypto.createHash('sha256').update(bodyStr, 'utf8').digest('hex')
  const canonical = [method.toUpperCase(), path, query, timestamp, nonce, bodySha256].join('\n')
  const signature = crypto.createHmac('sha256', API_SECRET).update(canonical, 'utf8').digest('hex')
  return { timestamp, nonce, signature }
}

async function createPayment() {
  const path = '/openapi/v1/payments'
  const body = JSON.stringify({
    merchantNo: '10080000001',
    outTradeNo: 'ORDER202610120002',
    amount: 1.00,
    paymentMethod: 'WECHAT',
    paymentMode: 'USER_SCAN',
    goodsName: '会员充值',
    userIp: '61.135.169.121',
    notifyUrl: 'https://api.partner.com/callback/payment',
    settlementMode: 'DELAYED'
  })
  const { timestamp, nonce, signature } = sign('POST', path, '', body)
  const resp = await fetch(BASE_URL + path, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=UTF-8',
      'X-App-Id': APP_ID,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature,
      'X-Idempotency-Key': 'idem-' + 'ORDER202610120002'
    },
    body
  })
  console.log(await resp.json())
}

11.2 Java 签名片段

String canonical = String.join("\n",
        "POST", path, rawQuery, timestamp, nonce, sha256Hex(bodyBytes));
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = HexFormat.of().formatHex(mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8)));

11.3 回调验签示例（Node.js）

app.post('/callback/payment', express.raw({ type: '*/*' }), (req, res) => {
  const timestamp = req.header('X-Callback-Timestamp')
  const nonce     = req.header('X-Callback-Nonce')
  const eventId   = req.header('X-Callback-Event-Id')
  const signature = String(req.header('X-Callback-Signature') || '').toLowerCase()

  const bodySha256 = crypto.createHash('sha256').update(req.body).digest('hex')
  const canonical  = [timestamp, nonce, eventId, bodySha256].join('\n')
  const expected   = crypto.createHmac('sha256', CALLBACK_SECRET)
                           .update(canonical, 'utf8').digest('hex')

  if (expected !== signature) return res.status(401).end()

  const event = JSON.parse(req.body.toString('utf8'))
  // 1. 按 event.eventId 幂等落库  2. 业务处理
  res.status(200).send('SUCCESS')   // 固定应答文本
})

12. 错误码与常见问题

12.1 平台错误码

见 2.1 统一响应包络。鉴权类失败为 HTTP 401 + A0002，开关类失败为 HTTP 503 + C0001。

12.2 退款错误码映射

12.3 常见问题（FAQ）

Q1：发起订单分账报「原支付订单的结算方式不支持订单分账」？

订单创建时 settlementMode 为 IMMEDIATE。订单分账仅支持延迟结算订单：请使用 settlementMode=DELAYED 创建新订单，支付成功并完成清算后再申请。

Q2：code=00000 但业务没成功？

00000 表示接口调用成功。支付/退款/分账为异步业务，请以 data.status、回调通知或查询接口为准。

Q3：签名一直失败？

按顺序排查：① 时间戳与服务器时差 ≤300 秒；② query 串与实际 URL 完全一致；③ body 用原始字节算 SHA-256；④ apiSecret 正确且未泄；⑤ 签名头是 64 位十六进制。

Q4：返回「请求已被处理或检测到重放」？

X-Nonce 在 TTL 内重复。每次请求生成新的随机 nonce；若为业务重试请更换 X-Idempotency-Key 场景或先查询原单状态。

Q5：回调收不到 / 收到但状态没更新？

① 确认 notifyUrl 公网可达且为 HTTPS；② 应答必须是 2xx + body SUCCESS；③ 业务状态未变化时平台不会重复推送；④ 长时间未收到可主动调用查询接口（refresh=true）兜底。

Q6：余额分账 recipientId 从哪里来？

先调用「申请入账方」接口，审核签约完成（status=COMPLETED）后返回的 recipientId 即可用于余额分账明细。

Q7：同一笔余额分账想重试？

仅当上次状态为 FAIL 时，可沿用原 businessNo 重新发起；PROCESSING/UNKNOWN 请先查询，SUCCESS 会直接回放原结果，不会重复划拨。