合利宝代付接口

概述

合利宝代付接口提供给商户代付到个人银行卡、企业银行账户的功能，商户可以根据代付需求结合合利宝代付接口设计代付流程，为个人和企业用户提供代付的应用场景。

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

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/21/3b6c0259"

快速决策树

用户咨询合利宝代付接入
        |
        +-- 代付到银行卡？
        |       +-- 是 --> 4.1 单笔代付 → 4.3 代付结果通知
        |
        +-- 查询代付状态？
        |       +-- 是 --> 4.2 单笔代付查询
        |
        +-- 对公转账？
        |       +-- 是 --> 4.1 单笔代付（P8_biz=B2B，P9_bankUnionCode 必填）
        |
        +-- 对私转账？
                +-- 是 --> 4.1 单笔代付（P8_biz=B2C）

接入路由表

| 场景 | 核心接口 | P1_bizType 值 | 适用场景 | |------|----------|---------------|----------| | 单笔代付 | 4.1 单笔代付 | Transfer | 代付到个人/企业银行账户 | | 单笔代付查询 | 4.2 单笔代付查询 | TransferQuery | 查询代付状态 | | 代付结果通知 | 4.3 代付结果通知 | - | 合利宝主动通知代付结果 |

场景关键词匹配

| 关键词 | 路由方式 | |--------|----------| | 代付、单笔代付、打款、转账到银行卡、对公转账、对私转账、代发 | 4.1 单笔代付 | | 代付查询、代付状态、打款状态、查询代付结果 | 4.2 单笔代付查询 | | 代付通知、打款通知、退汇通知 | 4.3 代付结果通知 |

以下关键词不触发本技能：

| 关键词 | 应使用技能 | |--------|------------| | 快捷支付、绑卡支付 | helipay-quickpay-integration | | 扫码支付、收款、主扫、被扫 | helipay-scanpay-integration | | 虚拟账户支付、子商户转账、E编号转账 | helipay-account-pay | | 商户结算、提现 | helipay-merchant-settlement | | 余额查询、对账单、电子回单 | helipay-public-products | | 商户进件、开户 | helipay-merchant-entry | | 延时分账、分账申请 | helipay-delayed-split |

完整代付流程

标准代付流程

4.1 单笔代付 → 提交代付请求 → 返回 rt2_retCode=0000 表示受理成功
    ↓
4.3 代付结果通知（异步回调，最多 5 次）
    或 4.2 单笔代付查询（主动查询）
    ↓ 确认终态：SUCCESS 成功 / FAIL 失败 / REFUND 退款

接口地址

| 环境 | 地址 | |------|------| | 测试环境 | http://test.trx.helipay.com/trx/transfer/interface.action | | 生产环境 | http://transfer.trx.helipay.com/trx/transfer/interface.action |

所有接口使用同一个请求地址，通过 P1_bizType 字段值区分具体接口。

请求通用规则

| 项目 | 说明 | |------|------| | 请求方法 | POST | | 请求格式 | application/x-www-form-urlencoded（form 表单） | | 响应报文类型 | application/json（JSON） | | 字符编码 | UTF-8 | | 签名算法 | SM3WITHSM2（固定） | | 接口识别 | 通过 P1_bizType 字段值判定是哪个接口 |

本接口没有公共参数，所有参数直接以 form 表单提交。

参数规范

| 规则 | 说明 | |------|------| | 订单号 | 50 字符以内，同一商户号下唯一 | | 金额 | 单位：元，最少值 0.01 |

核心接口详解

4.1 单笔代付

关键参数： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 交易类型 | P1_bizType | 是 | 固定 Transfer | | 商户订单号 | P2_orderId | 是 | 50 字符以内，同一商户号下唯一 | | 商户编号 | P3_customerNumber | 是 | 合利宝分配商户号 | | 金额 | P4_amount | 是 | 单位：元，最少 0.01 | | 银行编码 | P5_bankCode | 是 | 见附录银行编码表（CCB/ABC/CMBCHINA 等） | | 银行账户号 | P6_bankAccountNo | 是 | SM4 加密 | | 银行账户名 | P7_bankAccountName | 是 | 如"张三" | | 业务类型 | P8_biz | 是 | B2B：对公 / B2C：对私 | | 银行联行号 | P9_bankUnionCode | 条件 | 对公（B2B）时必填 | | 手续费收取方式 | P10_feeType | 是 | PAYER：付款方收取 / RECEIVER：收款方收取 | | 是否加急 | P11_urgency | 是 | 固定 true | | 打款备注 | P12_summary | 否 | 如"结算款"，必须使用通用或定制内容 | | 付款方信息 | P13_payerInfo | 否 | JSON 字符串，SM4 加密，不参与签名 | | 订单状态通知地址 | notifyUrl | 是 | 接收代付结果通知的地址，不参与签名 | | 签名 | sign | 是 | SM3WITHSM2 签名结果，需 URL 编码 | | 签名类型 | signatureType | 是 | 固定 SM3WITHSM2，不参与签名 | | 加密秘钥 | encryptionKey | 是 | SM4 key 经 SM2 加密后上送，不参与签名 |

P13_payerInfo 结构（需要时传）： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 付款方名称 | payerName | 是 | 付款方名称 | | 付款方简称 | payerShowName | 是 | 付款方简称 | | 付款方编号 | payerAccountNo | 是 | 付款方编号 | | 付款方账户号 | payerAcctNo | 是 | 付款方账户号 | | 付款方账户名 | payerAcctName | 是 | 付款方账户名 | | 版本 | version | 是 | 固定 V2 |

其他非签名字段： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 银联业务标识 | busPdtFlag | 00：一般性付款 / 03：营销返现 / 04：商户资金结算，不参与签名 | | 前序交易客户代码 | channelMerId | 不参与签名 | | 前序交易客户名称 | channelMerName | 不参与签名 |

返回参数： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 交易类型 | rt1_bizType | Transfer | | 返回码 | rt2_retCode | 0000 接收成功 | | 返回信息 | rt3_retMsg | 不参与签名 | | 商户编号 | rt4_customerNumber | 合利宝分配商户号 | | 商户订单号 | rt5_orderId | 商户订单号 | | 平台流水号 | rt6_serialNumber | 合利宝系统唯一流水号 | | 签名 | sign | SM3WITHSM2 签名结果 | | 签名类型 | signatureType | SM3WITHSM2 |

4.2 单笔代付查询

关键参数： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 交易类型 | P1_bizType | 是 | 固定 TransferQuery | | 商户订单号 | P2_orderId | 是 | 代付下单时的订单号 | | 商户编号 | P3_customerNumber | 是 | 合利宝分配商户号 | | 签名 | sign | 是 | SM3WITHSM2 签名结果 | | 签名类型 | signatureType | 是 | 固定 SM3WITHSM2，不参与签名 |

返回参数： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 交易类型 | rt1_bizType | TransferQuery | | 返回码 | rt2_retCode | 0000 成功 | | 返回信息 | rt3_retMsg | 不参与签名 | | 商户编号 | rt4_customerNumber | 合利宝分配商户号 | | 商户订单号 | rt5_orderId | 商户订单号 | | 平台流水号 | rt6_serialNumber | 平台流水号 | | 打款状态 | rt7_orderStatus | 见下方状态表 | | 返回信息 | rt8_reason | 不参与签名，如"收款账号、户名不符" | | 订单创建时间 | rt9_createDate | 不参与签名，格式 yyyy-MM-dd HH:mm:ss | | 订单完成时间 | rt10_completeDate | 不参与签名，格式 yyyy-MM-dd HH:mm:ss | | 订单金额 | rt11_amount | 不参与签名 | | 签名 | sign | SM3WITHSM2 签名结果 | | 签名类型 | signatureType | SM3WITHSM2 |

4.3 代付结果通知

合利宝主动通知，无请求参数。通知格式为 form 表单（application/x-www-form-urlencoded）。

通知参数（rt 开头）： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 交易类型 | rt1_bizType | Transfer | | 返回码 | rt2_retCode | 0000 | | 返回信息 | rt3_retMsg | 详情见返回码 | | 商户编号 | rt4_customerNumber | 商户编号 | | 商户订单号 | rt5_orderId | 商户订单号 | | 平台流水号 | rt6_serialNumber | 平台流水号 | | 打款状态 | rt7_orderStatus | 状态见下方 | | 通知类型 | rt8_notifyType | ORDER_STATUS：普通通知 / RETURN_REMITTANCE：退汇通知 | | 返回信息 | rt9_reason | 成功或失败原因 | | 订单创建时间 | rt10_createDate | yyyy-MM-dd HH:mm:ss | | 订单完成时间 | rt11_completeDate | yyyy-MM-dd HH:mm:ss | | 订单金额 | rt12_amount | 不参与签名 | | 签名 | sign | SM3WITHSM2 签名结果 | | 签名类型 | signatureType | SM3WITHSM2 |

商户接收到通知后必须返回纯文本 success，最多通知 5 次。

SM4 加密

需要 SM4 加密的字段： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 银行账户号 | P6_bankAccountNo | 银行卡号敏感信息 | | 付款方信息 | P13_payerInfo | JSON 字符串（如有） |

加密方式：

• 算法：SM4/CBC/PKCS7Padding
• 固定 IV 值：AQ4Zvt54xKn9QaW86ZzWdg==（base64 格式，使用前需解码）
• SM4 密钥：商户随机生成 128 比特流
• 加密密钥：使用平台公钥 SM2 加密 SM4 密钥后填入 encryptionKey

使用方式：将需要加密的敏感字段明文传给 helipay-sm2 技能，获取密文填入请求参数。

签名规则

固定不参与签名的字段：

• sign - 签名结果本身
• signatureType - 签名类型标识
• encryptionKey - 加密秘钥
• notifyUrl - 通知地址
• P13_payerInfo - 付款方信息（文档明确标注排除签名）
• busPdtFlag - 银联业务标识
• channelMerId - 前序交易客户代码
• channelMerName - 前序交易客户名称

拼接规则：

1. 除上述不参与签名的字段外，其他参数按变量名顺序拼接：&P1值&P2值&P3值...
2. 参与签名的字段，不传值也要保留连接符号 &
3. 中文不需要 URL Encode
4. 尾部不追加秘钥（仅 SM3WITHSM2 签名）
5. 签名结果需 URL 编码：URLEncoder.encode(sign, "UTF-8")

签名示例：

&Transfer&p_20170306114605&C1800000002&0.01&CCB&6216731234963158742&张三&B2C&&&true&结算

示例中 P9_bankUnionCode、P10_feeType 不传值但保留连接符。

签名计算：sign = SM2(待签名字符串, 商户SM2私钥)

回调处理

| 项目 | 说明 | |------|------| | 通知方法 | POST，application/x-www-form-urlencoded（form 表单） | | 通知次数 | 最多 5 次 | | 响应要求 | 处理成功后返回纯文本 success |

回调验签规则与请求签名规则一致（除 sign、signatureType、rt12_amount 外所有参数按顺序拼接）。

打款状态

| 状态 | 描述 | 说明 | |------|------|------| | RECEIVE | 已接收 | 已接收到请求 | | INIT | 初始化 | 订单初始化 | | DOING | 处理中 | 处理中 | | SUCCESS | 成功 | 打款成功 | | FAIL | 失败 | 打款失败 | | REFUND | 退款 | 已退款 |

返回码

| 返回码 | 描述 | 说明 | |--------|------|------| | 0000 | 接收成功 | | | 0001 | 订单已存在 | 订单号重复 | | 0002 | 接收失败 | | | 0003 | 账户余额不足 | | | 0004 | 账户状态异常 | | | 0005 | 订单不存在 | | | 0006 | 打款超过限额 | |

银行编码表

| 编码 | 银行 | 编码 | 银行 | |------|------|------|------| | ABC | 中国农业银行 | CMBCHINA | 招商银行 | | CCB | 中国建设银行 | BOCO | 交通银行 | | BOC | 中国银行 | CMBC | 中国民生银行 | | CGB | 广发银行 | HXB | 华夏银行 | | POST | 中国邮政储蓄银行 | ECITIC | 中信银行 | | CEB | 中国光大银行 | PINGAN | 平安银行 | | CIB | 兴业银行 | SPDB | 浦发银行 | | BCCB | 北京银行 | BON | 南京银行 | | NBCB | 宁波银行 | BEA | 东亚银行 | | SRCB | 上海农商银行 | SHB | 上海银行 | | CZB | 浙商银行 | TCCB | 天津银行 | | HSBANK | 徽商银行 | HFBANK | 恒丰银行 | | CBHB | 渤海银行 | JSB | 江苏银行 | | CITI | 花旗银行 | THX | 贵阳银行 | | HANGSENGBANK | 恒生银行 | GDNYBANK | 南粤银行 | | LZBANK | 兰州银行 | | |

打款备注说明

代付接口中的打款备注必须按照通用或商户定制的内容填写，不传或错传则默认为"结算"。

| 通用备注 | 说明 | |----------|------| | 结算 | 默认值 | | 工资奖金 | | | 供应链款项 | | | 交易退款 | | | 公共事业费用 | |

定制内容需联系业务人员在合利宝系统平台进行内容定制。

注意事项

• 没有公共参数：所有参数直接以 form 提交，不需要 body 加密。
• SM4 加密：银行账户号（P6_bankAccountNo）和付款方信息（P13_payerInfo）需要 SM4/CBC/PKCS7Padding 加密，固定 IV 值为 AQ4Zvt54xKn9QaW86ZzWdg==。
• 不参与签名的字段：sign、signatureType、encryptionKey、notifyUrl、P13_payerInfo、busPdtFlag、channelMerId、channelMerName。
• 签名结果需 URL 编码：URLEncoder.encode(sign, "UTF-8") 后填入 sign 字段。
• 对公转账联行号必填：P8_biz=B2B 时 P9_bankUnionCode 必填。
• 加急固定传 true：P11_urgency 固定传 true。
• 回调必须返回 success：接收到通知后返回纯文本 success，最多通知 5 次。
• 做好回调幂等处理：可能重复通知，订单状态以回调或查询为准。
• 各接口具体的请求参数、返回参数、返回码以最新文档为准，请用上方 curl 命令获取。

生成时的说明要求

最终回答需要包含：

• 接口请求方式：明确告知接口是 POST form 表单格式（application/x-www-form-urlencoded），不是 JSON；通过 P1_bizType 字段值来判定是哪个接口。
• 接口字段说明：列出所有请求参数（以及不带 P 开头的参数）、返回参数的完整说明，明确哪些字段需要 SM4 加密、哪些字段参与签名。
• 签名源串拼接规则：按 &P1值&P2值&P3值... 顺序拼接（除 sign、signatureType、encryptionKey、notifyUrl、P13_payerInfo、busPdtFlag、channelMerId、channelMerName 外的所有参数），参与签名的字段，不传值也要保留连接符号 &，仅 SM3WITHSM2 签名，不追加秘钥。签名结果需 URL 编码。
• SM4 加密字段清单：明确告知用户 P6_bankAccountNo（银行账户号）和 P13_payerInfo（付款方信息）需要调用 helipay-sm2 技能进行 SM4/CBC/PKCS7Padding 加密，固定 IV 值为 AQ4Zvt54xKn9QaW86ZzWdg==（base64）。SM4 密钥用 SM2 公钥加密后填入 encryptionKey。
• 代码示例：提供完整的请求参数组装、签名、调用示例（Java/Python 等，根据用户要求）。
• 配合 helipay-sm2 技能使用：
  • 签名：将拼接好的签名源串传给 helipay-sm2 技能，获取 SM3withSM2 签名结果。
  • SM4 加密：将 P6_bankAccountNo 和 P13_payerInfo 明文传给 helipay-sm2 技能，获取密文填入请求参数。SM4 密钥用平台公钥 SM2 加密。
  • SM4 解密（回调处理）：本接口响应数据为明文 JSON，无需解密。
• JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
• 明确说明：本技能只处理合利宝代付接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
• 提醒：签名源串的字段顺序、排除字段、证书格式必须与合利宝官方文档一致；对公转账（B2B）时联行号必填；加急固定传 true；打款备注必须使用通用或定制内容。
• 金额单位：元（不是分），最少 0.01 元。