shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

合利宝接口对接_虚拟账户支付V001

合利宝接口对接、虚拟账户支付产品接口

personAuthor: LuckyKhubModelScope
downloadDownload package

合利宝虚拟账户支付接口

概述

合利宝虚拟账户支付接口提供给同一平台商下子商户间的账户支付，商户可以根据需求结合合利宝接口设计资金划拨流程，为个人和企业用户提供的应用场景。

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

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/52/29edf57f"

快速决策树

用户咨询合利宝虚拟账户支付接入
        |
        +-- 子商户间转账/资金划拨？
        |       +-- 是 --> 3.1 下单接口 → 判断是否需要短信验证
        |
        +-- 需要短信验证的资金划拨？
        |       +-- 是 --> 3.4 获取验证码 → 3.5 确认支付
        |
        +-- 活动补贴类支付（基于原交易）？
        |       +-- 是 --> 3.1 下单接口（orderType=ALLOWANCE）
        |
        +-- 担保交易？
        |       +-- 是 --> 3.1 下单（inEscrow=true）→ 3.8 担保确认/撤销
        |
        +-- 查询订单状态？
        |       +-- 是 --> 3.2 订单查询接口
        |
        +-- 退款？
        |       +-- 是 --> 3.6 退款接口 → 3.7 退款查询

接入路由表

| 场景 | 核心接口 | P1_bizType 值 | 适用场景 | |------|----------|---------------|----------| | 账户支付下单 | 3.1 下单接口 | AccountPaySub | 子商户间转账、资金划拨、活动补贴 | | 订单查询 | 3.2 订单查询 | AccountPayQuery | 查询支付状态 | | 获取短信验证码 | 3.4 获取验证码 | AccountPayValidateCode | 非担保资金划拨需短验时获取验证码 | | 确认支付 | 3.5 确认支付 | AccountPayConfirmPay | 非担保资金划拨需短验时确认支付 | | 退款 | 3.6 退款接口 | AccountPayRefund | 发起退款 | | 退款查询 | 3.7 退款查询 | AccountPayRefundQuery | 查询退款状态 | | 担保确认/撤销 | 3.8 担保确认 | AccountPayEscrowConfirm | 担保交易确认支付或撤销 |

场景关键词匹配

| 关键词 | 路由方式 | |--------|----------| | 虚拟账户支付、账户支付、子商户转账、E编号转账、资金划拨 | 3.1 下单接口 | | 活动补贴、ALLOWANCE | 3.1 下单接口（orderType=ALLOWANCE） | | 担保交易、担保确认、担保撤销、ESCROW | 3.1 下单 + 3.8 担保确认 | | 短信验证码、获取验证码、短验 | 3.4 获取验证码 | | 确认支付、短信确认 | 3.5 确认支付 | | 订单查询、支付状态查询、查单 | 3.2 订单查询 | | 退款、退货、退款申请 | 3.6 退款接口 | | 退款查询、退款状态 | 3.7 退款查询 | | 回调通知、异步通知、支付回调 | serverCallbackUrl 回调 |

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

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

完整支付流程

资金划拨类（不需要短信验证）

3.1 下单接口 → 返回 DOING 状态 → 3.2 订单查询确认终态 → 完成

资金划拨类（需要短信验证）

3.1 下单接口 → 返回 RECEIVE 状态
    ↓
3.4 获取验证码接口 → 发送短信到用户手机
    ↓
3.5 确认支付接口 → 传入短信验证码 → 返回 DOING 状态
    ↓
3.2 订单查询确认终态 → 完成

活动补贴类（不需要短信验证）

3.1 下单接口（orderType=ALLOWANCE，需传 productType + associatedOrderNo）
    ↓ 返回 DOING 状态
3.2 订单查询确认终态 → 完成

担保交易类

3.1 下单接口（inEscrow=true）→ 返回 IN_ESCROW 状态
    ↓
3.8 担保确认接口（operateType=CONFIRM）→ 返回 DOING 状态
或 3.8 担保撤销接口（operateType=CANCEL）→ 返回 ESCROW_CANCELLED 状态
    ↓
3.2 订单查询确认终态 → 完成

接口地址

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

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

请求通用规则

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

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

参数规范

| 规则 | 说明 | |------|------| | 时间戳 | yyyy-MM-dd_HH:mm:ss.SSS（如 2018-05-14_10:20:30.400） | | 订单号 | 50 字符以内，同一商户号下唯一 | | 金额 | 单位：元，小数点后最多两位，不能小于等于零 |

核心接口详解

3.1 下单接口

关键参数： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 交易类型 | P1_bizType | 是 | 固定 AccountPaySub | | 签名类型 | P2_signType | 是 | 固定 SM3WITHSM2 | | 时间戳 | P3_timestamp | 是 | 格式 yyyy-MM-dd_HH:mm:ss.SSS | | 商户订单号 | P4_orderId | 是 | 50 字符以内，同一商户号下唯一 | | 付款商户商编 | P5_customerNumber | 是 | 合利宝分配商户号 | | 拓展参数 | P6_ext | 是 | JSON 字符串，结构见下方 | | 签名 | sign | 是 | SM3WITHSM2 签名结果 |

P6_ext 结构： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 收款商户商编 | inMerchantNo | 是* | 与付款商户隶属同一平台商（使用 splitBillRules 时可不填） | | 订单类型 | orderType | 是 | 固定 TRANSFER（当前不支持其他类型） | | 资金来源 | payerAccountSource | 是 | STD：标准 / SPLITTABLE：储值 / AVAILABLE_BALANCE：可结算金额 | | 订单金额 | amount | 是 | 不能小于等于零，小数点后最多两位 | | 服务器通知地址 | serverCallbackUrl | 否 | 异步通知地址，若填值则异步通知商户支付结果 | | 商品名称 | goodsName | 是 | 如"活动补贴" | | 订单备注 | orderDesc | 否 | 备注信息 | | 原订单产品类型 | productType | 条件 | orderType=ALLOWANCE 时必填（APPPAY/ONLINE/QUICKPAY） | | 原订单商户订单号 | associatedOrderNo | 条件 | orderType=ALLOWANCE 时必填 | | 担保交易标识 | inEscrow | 否 | true/false，仅 orderType=TRANSFER 时可填 | | 收款分账规则串 | splitBillRules | 否 | 若无要求分账则不用传，JSON 数组格式 | | 手续费承担方向 | belongsType | 否 | PAYER：付款方承担 / RECEIVER：收款方承担 | | 待分账金额 | presetSplitAmount | 否 | orderType=TRANSFER 且 splitBillRules 为空时可填 |

splitBillRules 格式（需要分账时传）：

[
  {"splitBillMerchantNo": "E1800000009", "splitBillAmount": 1.00, "splitBillFee": 0.0}
]

返回参数： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 签名类型 | rt2_signType | SM3WITHSM2 | | 时间戳 | rt3_timestamp | 时间戳 | | 是否需要验签 | rt4_success | true/false，若 false 则 rt6_retMsg 返回错误信息 | | 响应码 | rt5_retCode | 0000 接收成功 | | 返回信息 | rt6_retMsg | 状态说明 | | 商户订单号 | rt7_orderId | 商户订单号 | | 商户编号 | rt8_customerNumber | 商户编号 | | 平台流水号 | rt9_serialNumber | 合利宝虚拟账户支付唯一平台流水号 | | 订单状态 | rt10_orderStatus | 见下方订单状态表 | | 拓展参数 | rt11_ext | JSON 字符串，值暂固定为 {} | | 签名 | sign | 若 rt4_success 为 true，此字段非空 |

3.2 订单查询接口

关键参数： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 交易类型 | P1_bizType | 是 | 固定 AccountPayQuery | | 签名类型 | P2_signType | 是 | 固定 SM3WITHSM2 | | 时间戳 | P3_timestamp | 是 | 格式 yyyy-MM-dd_HH:mm:ss.SSS | | 商户订单号 | P4_orderId | 是 | 商户系统内部订单号 | | 商户编号 | P5_customerNumber | 是 | 合利宝分配商户号 | | 签名 | sign | 是 | SM3WITHSM2 签名结果 |

返回参数（比下单接口多几个字段）： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 交易类型 | rt1_bizType | AccountPayQuery | | 时间戳 | rt3_timestamp | 时间戳 | | 是否需要验签 | rt4_success | true/false | | 响应码 | rt5_retCode | 0000 成功 | | 返回信息 | rt6_retMsg | 状态说明 | | 商户订单号 | rt7_orderId | 商户订单号 | | 商户编号 | rt8_customerNumber | 商户编号 | | 平台流水号 | rt9_serialNumber | 平台流水号 | | 订单状态 | rt10_orderStatus | 订单状态 | | 订单金额 | rt11_amount | 订单金额 | | 订单状态说明 | rt12_reason | 如"商户余额不足" | | 拓展参数 | rt13_ext | JSON 字符串（含 presetSplitAmount、splittableAmount） | | 签名 | sign | 若 rt4_success 为 true，此字段非空 |

3.6 退款接口

关键参数： | 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 交易类型 | P1_bizType | 是 | 固定 AccountPayRefund | | 签名类型 | P2_signType | 是 | 固定 SM3WITHSM2 | | 时间戳 | P3_timestamp | 是 | 格式 yyyy-MM-dd_HH:mm:ss.SSS | | 商户原交易订单号 | P4_orderId | 是 | 原交易订单订单号 | | 退款发起方商编 | P5_customerNumber | 是 | 合利宝分配商户号 | | 退款订单号 | P6_refundOrderId | 是 | 商户自定义退款订单号，同一商户退款订单号唯一 | | 退款详细参数 | P7_refundDetail | 是 | JSON 字符串，结构见下方 | | 异步回调地址 | P8_callbackUrl | 否 | 订单终态时回调通知商户地址 | | 签名 | sign | 是 | SM3WITHSM2 签名结果 |

P7_refundDetail 格式：

[{"merchantNo": "E1800000000", "refundAmount": 10}]

签名规则

固定不参与签名的字段：

  • sign - 签名结果本身

拼接规则：

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

签名示例：

&AccountPaySub&SM3WITHSM2&2018-06-06_14:21:00.945&p_20180606142100&E1800001337&{"amount":10,"associatedOrderNo":"p_20180606142100","goodsName":"苹果7","inMerchantNo":"E1800001212","orderDesc":"","orderType":"TRANSFER","productType":"APPPAY"}

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

回调处理

| 项目 | 说明 | |------|------| | 通知方法 | POST，application/x-www-form-urlencoded（form 表单） | | 触发时机 | 订单完成支付之后 | | 响应要求 | 处理成功后返回纯文本 success |

回调参数（与查询接口返回参数类似，rt 开头）：

  • rt1_bizType: AccountPay
  • rt4_success: true
  • rt5_retCode: 0000
  • rt7_orderId: 商户订单号
  • rt8_customerNumber: 商户编号
  • rt9_serialNumber: 平台流水号
  • rt10_orderStatus: SUCCESS
  • rt11_amount: 订单金额
  • rt13_ext: JSON 字符串（含 presetSplitAmount、splittableAmount）
  • sign: 签名结果

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

返回码

| 返回码 | 描述 | 说明 | |--------|------|------| | 0000 | 接收成功 | | | 0001 | 系统配置有误 | rt6_retMsg 记录详细错误信息 | | 0002 | 请求参数错误 | rt6_retMsg 记录详细错误信息 | | 0003 | 非法交易 | | | 0004 | 短信验证码获取失败了 | | | 0005 | 账户状态异常 | | | 0006 | 未找到关联订单号对应的记录 | 检查原始订单号 | | 0007 | 订单已存在 | 下单订单号重复 | | 0008 | 订单不存在 | 短验/确认支付使用的单号与下单不一致 | | 0009 | 订单状态异常 | | | 0010 | 账号余额不足 | 付款方账户余额不足 | | 0011 | 预存手续费账户余额不足 | | | 0012 | 订单已确认支付 | 确认支付接口返回，请勿重复提交 | | 0013 | 短信验证码错误或已过期 | | | 0014 | 退款金额超出可退款金额 | | | 0015 | 账户余额不足 | 账户余额不足或者当日资金不足 | | 0016 | 手续费账户已关闭 | 原交易由手续费账户支付手续费，该账户关闭后不支持退款 | | 0100 | 请求太频繁，请稍后再试 | |

订单类型

| 订单类型 | 描述 | 说明 | |----------|------|------| | TRANSFER | 资金划拨 | 不基于原交易的虚拟账户支付 | | ALLOWANCE | 活动补贴 | 基于原交易的虚拟账户支付 |

订单状态

| 状态 | 描述 | 说明 | |------|------|------| | RECEIVE | 接收成功 | 需短验的非担保资金划拨交易，下单成功后返回此状态 | | IN_ESCROW | 担保中 | 担保资金划拨类交易用，下单后返回此状态 | | ESCROW_CANCELLED | 担保撤销 | 担保撤销后状态 | | DOING | 处理中 | 不需要短验的下单成功/确认支付成功/担保确认后返回此状态；终态需通过查询或回调确认 | | SUCCESS | 成功 | 订单终态 | | FAIL | 失败 | 订单终态 |

注意事项

  • orderType 固定传 TRANSFER：当前不支持其他订单类型。
  • 没有公共参数：所有参数直接以 form 提交，不需要 body 加密。
  • splitBillRules 和 presetSplitAmount：若无要求分账，则不用传。
  • 时间戳格式特殊：yyyy-MM-dd_HH:mm:ss.SSS（不是常见的 yyyyMMddHHmmss）。
  • 签名结果需 URL 编码：URLEncoder.encode(sign, "UTF-8") 后填入 sign 字段。
  • 拓展参数 P6_ext：是 JSON 字符串，暂固定为 {}，实际业务字段放在 ext 内部。
  • 敏感信息保护：不要在日志中明文记录商户号、订单号等敏感信息。
  • 做好回调幂等处理：可能重复通知，订单状态以回调或查询为准。
  • 各接口具体的请求参数、返回参数、返回码以最新文档为准，请用上方 curl 命令获取。

生成时的说明要求

最终回答需要包含：

  • 接口请求方式：明确告知接口是 POST form 表单格式（application/x-www-form-urlencoded），不是 JSON；通过 P1_bizType 字段值来判定是哪个接口。
  • 接口字段说明：列出所有请求参数（以及不带 P 开头的参数）、返回参数的完整说明，明确哪些字段需要 SM4 加密、哪些字段参与签名。
  • 签名源串拼接规则：按 &P1值&P2值&P3值... 顺序拼接（除 sign 外的所有参数），参与签名的字段，不传值也要保留连接符号 &，仅 SM3WITHSM2 签名，不追加秘钥。签名结果需 URL 编码。
  • SM4 加密字段清单：明确告知用户哪些字段需要调用 helipay-sm2 技能进行 SM4 加密。本接口无 SM4 加密字段，可忽略此步骤。
  • 代码示例：提供完整的请求参数组装、签名、调用示例（Java/Python 等，根据用户要求）。
  • 配合 helipay-sm2 技能使用：
    • 签名：将拼接好的签名源串传给 helipay-sm2 技能，获取 SM3withSM2 签名结果。
    • SM4 加密：本接口无 SM4 加密字段，可忽略。
    • SM4 解密（回调处理）：本接口响应数据为明文 JSON，无需解密。
  • JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
  • 明确说明：本技能只处理合利宝虚拟账户支付接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
  • 提醒：签名源串的字段顺序、排除字段、证书格式必须与合利宝官方文档一致；orderType 目前只能传 TRANSFER；splitBillRules 和 presetSplitAmount 若无分账要求则不用传。