合利宝延时分账接口

概述

延时分账用于未在下单时做实时分账的订单，在支付成功后发起分账请求。如订单已做了实时分账（请求参数中传了 ruleJson），则不适用本技能。

编写代码前务必先获取最新文档：

# 可分账金额解冻接口
curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/26/69b6f0fd"

# 延时分账接口规范（申请分账/分账查询/分账退回/分账退回查询）
curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/26/7a4727dd"

版本说明

| 版本 | 解冻要求 | 退款要求 | |------|----------|----------| | V2（默认） | 不需要解冻接口 | 可直接分账退回 | | V3 | 需先调用解冻接口解冻资金 | 退款前必须确保资金已解冻 |

除非明确要 V3 版本，否则默认使用 V2 接口，无需解冻。

适用场景判断

用户需要分账
    |
    +-- 下单时已传 ruleJson 做实时分账？
    |       +-- 是 --> 不适用本技能，走原支付接口
    |
    +-- 分账退回，且为 V3 版本？
    |       +-- 是 --> 先调用解冻接口，再分账退回
    |
    +-- 默认 V2 或未特别说明？
            +-- 是 --> 直接申请分账/分账退回，无需解冻

接口决策表

| 接口 | 请求路径（拼在域名后） | 是否常用 | |------|----------------------|----------| | 可分账金额解冻 | /trx/splittableAmount/adjust | 仅 V3 退款前需要 | | 解冻结果查询 | /trx/splittableAmount/adjust/query | 仅 V3 退款前需要 | | 申请分账 | /trx/delayedSplit/apply | 核心接口 | | 分账查询 | /trx/delayedSplit/apply/query | 查询分账状态 | | 分账退回 | /trx/delayedSplit/back | 退回已分账资金 | | 分账退回查询 | /trx/delayedSplit/back/query | 查询退回状态 |

完整请求地址：

| 环境 | 地址 | |------|------| | 测试环境 | http://test.trx.helipay.com + 接口路径 | | 生产环境 | https://pay.trx.helipay.com + 接口路径 |

请求通用规则

| 项目 | 说明 | |------|------| | 请求方法 | POST | | 请求格式 | application/json（JSON Body） | | 加密方式 | data 域 SM4 对称加密，SM4 密钥用 SM2 公钥加密后填入 encryptionKey | | 签名方式 | 仅 SM3WITHSM2，对加密后的 data 字符串签名 | | 字符编码 | UTF-8 |

公共参数（所有接口通用）

请求公共参数

| 字段名 | 变量名 | 必填 | 说明 | 参与签名 | |--------|--------|------|------|----------| | 订单实体 | data | 是 | 接口业务参数 JSON，经 SM4 加密后的字符串 | 是 | | 商户号 | customerNumber | 是 | 合利宝分配的商户号（子商户收单传发起方 E 商编） | 否 | | 加密密钥 | encryptionKey | 是 | 随机 SM4 密钥，经 SM2 加密后 BASE64 编码上送 | 否 | | 签名方式 | signType | 是 | 固定 SM3WITHSM2 | 否 | | 签名 | sign | 是 | 对加密后的 data 字符串做 SM3WITHSM2 签名 | 否 | | 时间戳 | timestamp | 是 | 格式 yyyyMMddHHmmss，14位精确到秒 | 否 | | 版本号 | version | 是 | 固定 1.0 | 否 | | 证书序列号 | certSerialNumber | 否 | 证书序列号 | 否 |

返回公共参数

| 字段名 | 变量名 | 说明 | 参与签名 | |--------|--------|------|----------| | 返回码 | code | 0000=成功 | 否 | | 返回信息 | message | 成功/失败描述 | 否 | | 签名方式 | signType | SM3WITHSM2 | 否 | | 签名 | sign | 服务端对 data 域的签名 | 否 | | 订单实体 | data | SM4 加密后的响应数据，需解密 | 否 |

签名与加密规则

签名规则

将 data 域的业务参数组装成 JSON 对象
将 JSON 对象转为字符串
用 SM4 加密该 JSON 字符串
对加密后的 data 字符串使用商户私钥进行 SM3WITHSM2 签名
签名结果填入 sign 字段

签名只针对加密后的 data 字符串。除 data 外的公共参数均不参与签名。

加密规则

商户随机生成 128 位 SM4 密钥
用 SM4 加密 data 域的 JSON 字符串
用平台公钥（SM2）加密该 SM4 密钥
将加密后的 SM4 密钥 BASE64 编码，填入 encryptionKey 字段

data 域组装示例

{
  "orderId": "20170708195911000001",
  "originalOrderId": "TRADE_123456",
  "originalProductCode": "APPPAY",
  "ruleJson": [
    {"splitBillMerchantNo": "E1807444171", "splitBillAmount": 10},
    {"splitBillMerchantNo": "E1807444058", "splitBillAmount": 10}
  ]
}

关键：ruleJson 的值是原生 JSON 数组 [{...}]，不是字符串 "[{...}]"。不要对 ruleJson 单独做 json_encode/JSON.stringify，它直接作为数组放在 data 对象中。整个 data 对象整体序列化后再做 SM4 加密。

响应验签与解密

从响应体取出 data 字符串
用平台公钥对 sign 进行验签（验证 data 的完整性）
验签通过后，用商户 SM2 私钥解密 encryptionKey 获得 SM4 密钥
用 SM4 密钥解密 data 获得响应 JSON

回调签名规则

支付/退款结果异步回调的签名规则不同于请求：

将回调参数中非空值的参数按参数名 ASCII 码从小到大排序
使用 URL 键值对格式拼接：key1=value1&key2=value2...
空值参数不参与签名
参数名区分大小写
用 SM3WITHSM2 算法签名，结果 Base64 编码
回调可能增加扩展字段，验签时需兼容

注意事项

本技能只适用于未在下单时做实时分账的订单。已做实时分账的订单不适用。
如需实时分账，应在原支付请求参数中传 ruleJson，由原接口完成分账。
ruleJson 是原生 JSON 数组，不是 JSON 字符串：组装 data 时 ruleJson 直接赋值为数组对象 [{...}]，不要用 json_encode/JSON.stringify 将其转为字符串 "[{...}]"，否则服务端解析失败。
默认使用 V2 版本，不需要调用解冻接口。
V3 版本分账退回前必须先调用解冻接口解冻资金。
分账规则中同一商编不可重复，不可传分账发起方自己。
金额单位为元，最多保留两位小数。
使用延时分账接口前需联系商务开通分账产品。
子商户收单时 customerNumber 传的是发起方 E 商户编号。
分账退回时公共参数的 customerNumber 传的是当时交易的收款方商编。
各接口具体的请求 data 字段、返回参数、返回码以最新接口文档为准，请用上方 curl 命令获取。

生成时的说明要求

最终回答需要包含：

接口字段说明：列出请求公共参数（data、customerNumber、encryptionKey、signType、sign、timestamp、version、certSerialNumber）、各接口 data 对象内请求参数、返回参数的完整说明（以最新文档为准）。
签名源串拼接规则：对加密后的 data 字符串使用商户私钥进行 SM3WITHSM2 签名。除 data 外的公共参数均不参与签名。回调签名按参数名 ASCII 排序后 key=value 拼接，空值不参与签名。
SM4 加密字段清单：所有接口的 data 域（业务参数 JSON）需要 SM4 加密，SM4 密钥用 SM2 公钥加密后填入 encryptionKey。
代码示例：提供完整的请求参数组装、SM4 加密、SM2 加密密钥、签名、调用示例（Java/Python 等，根据用户要求）。
配合 helipay-sm2 技能使用：
- 签名：将加密后的 data 字符串传给 helipay-sm2 技能，获取 SM3WITHSM2 签名结果。
- SM4 加密：将 data 域的业务参数 JSON 明文传给 helipay-sm2 技能进行 SM4 加密；同时用 SM2 公钥加密 SM4 密钥。
- SM4 解密（回调/响应处理）：将密文（响应 data 字段或回调密文字段）传给 helipay-sm2 技能进行 SM4 解密。
JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
明确说明：本技能只处理合利宝延时分账接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
提醒：签名源串（加密后的 data 字符串）、排除字段（除 data 外的所有公共参数）、证书格式必须与合利宝官方文档一致；请求格式为 JSON Body（不是 form 表单），data 域加密后上送。