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

合利宝接口对接_快捷

合利宝接口对接，包含国密sm2、快捷和通用收银台产品接口。本项目是快捷产品接口

personAuthor: LuckyKhubModelScope
downloadDownload package

合利宝快捷支付接口对接指南

接口版本说明

合利宝快捷支付接口有三个版本，本技能同时支持权益类和普通快捷：

| 版本 | 说明 | |------|------| | 普通快捷 | 标准快捷支付接口，基础功能 | | 权益类快捷 | 在普通快捷基础上增加权益相关字段，向下兼容普通快捷 | | 预约支付快捷 | 支持预约扣款，字段结构不同（需额外确认） |

如何判断您对接的版本：

  • 如果您不确定对接的是哪个版本，可以直接使用此技能，然后根据实际接口返回调整参数
  • 权益类接口在普通快捷基础上增加了额外字段，如果只是用普通功能，可以忽略这些额外字段
  • 如有疑问，请联系合利宝业务人员确认

文档获取方式

合利宝快捷支付接口文档通过在线 API 动态获取：

# 获取完整接口文档
curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/37/8ca9c6e4"

编写代码前务必先获取最新文档，文档内包含完整的接口参数、代码示例和返回码说明。

快速决策树

用户咨询合利宝快捷支付接入
        |
        +-- 绑卡的同时完成支付？
        |       +-- 是 --> 方式一：首次支付（4.1→4.2→4.3）
        |
        +-- 先绑卡，后续再支付？
        |       +-- 是 --> 方式二：鉴权绑卡（4.4→4.5→4.6）
        |
        +-- 免输卡号，跳转银行页面绑卡？
                +-- 是 --> 方式三：一键绑卡（4.15→4.16）

接入路由表

| 场景 | 推荐方式 | 核心接口 | P1_bizType 值 | 适用场景 | |------|----------|----------|---------------|----------| | 绑卡并支付 | 方式一：首次支付 | 4.1 首次支付 → 4.2 短信 → 4.3 确认支付 | QuickPayFirstPayPreOrderSP | 用户首次绑卡时同步完成支付 | | 先绑卡后支付 | 方式二：鉴权绑卡 | 4.4 预下单 → 4.5 短信 → 4.6 绑卡 | QuickPaySignOrderSP | 绑定银行卡，后续多次支付 | | 免输卡号绑卡 | 方式三：一键绑卡 | 4.15 一键绑卡 → 4.16 结果查询 | QuickPayBindBankCard | 跳转银行页面完成绑卡 | | 绑卡后再次支付 | 绑卡支付 | 4.7 预下单 → 4.9 绑卡支付 | QuickPayPayOrderSP | 使用已绑卡号完成支付 | | 查询支付结果 | 订单查询 | 4.11 订单查询 | QuickPayQuerySP | 根据订单号查询支付状态 | | 解除银行卡绑定 | 解绑接口 | 4.12 银行卡解绑 | QuickPayUnBindSP | 用户主动解绑银行卡 |

场景关键词匹配

| 关键词 | 路由方式 | |--------|----------| | 权益、权益支付、权益类快捷、权益快捷、权益代扣、权益交易 | 权益类快捷支付 | | 首次支付、绑卡支付、边绑卡边支付、第一次支付、绑定并支付、同步支付 | 方式一：首次支付 | | 鉴权绑卡、先绑卡后支付、绑定银行卡、签约、协议签约、绑卡收款 | 方式二：鉴权绑卡 | | 一键绑卡、免输卡号、跳转银行页面、银联签约、H5 绑卡、工行绑卡 | 方式三：一键绑卡 | | 绑卡支付、再次支付、选卡支付、用已绑卡支付、快捷支付 | 绑卡支付（4.7+4.9） | | 订单查询、支付结果查询、查单、查询接口 | 4.11 订单查询 | | 解绑、解除绑定、删除银行卡、解约 | 4.12 银行卡解绑 | | 回调通知、异步通知、支付回调、服务器通知 | 4.10 异步通知接口 | | 短信验证码、发送验证码、验证码短信 | 4.2/4.5/4.8 短信接口 |

接口地址

| 环境 | 地址 | |------|------| | 测试环境 | https://test.trx.helipay.com/trx/quickPayApi/interface.action | | 生产环境 | https://quickpay.trx.helipay.com/trx/quickPayApi/interface.action |

⚠️ 注意: 测试环境也是真实交易，请用小金额测试！

三种支付方式详解

方式一：首次支付（绑卡 + 支付同步）

流程：

4.1 首次支付（预下单）
    ↓ 返回绑卡 ID
4.2 首次支付短信
    ↓ 发送验证码到银行预留手机号
4.3 确认支付
    ↓ 支付成功，返回 bindId

适用场景：

  • 用户首次使用银行卡支付
  • 绑卡的同时完成首次支付
  • 电商首次下单、快捷收款

关键参数：

  • P1_bizType: QuickPayFirstPayPreOrderSP
  • P9_cardNo: 银行卡号（SM4 加密）
  • P13_phone: 银行预留手机号（SM4 加密）
  • P23_serverCallbackUrl: 支付回调地址

返回结果：

  • rt10_bindId: 绑卡 ID（后续支付使用）

方式二：鉴权绑卡（先绑卡后支付）

流程：

绑卡阶段：
4.4 鉴权绑卡预下单
    ↓
4.5 鉴权绑卡短信
    ↓
4.6 鉴权绑卡 → 获取 bindId

支付阶段（后续）：
4.7 绑卡支付预下单
    ↓
4.9 绑卡支付

适用场景：

  • 用户中心绑定银行卡
  • 后续多次支付使用同一张卡
  • 会员充值、周期性缴费

关键参数：

  • 4.4/4.5/4.6 必须使用同一订单号
  • 4.7/4.9 必须使用同一订单号（与绑卡订单号不同）
  • 4.7 需传入 P3_bindId（从 4.6 返回获取）

方式三：一键绑卡（免输卡号）

流程：

绑卡阶段：
4.15 一键绑卡
    ↓ 返回 HTML form 表单
前端自动提交跳转银行页面
    ↓ 用户银行页面完成鉴权
4.16 一键绑卡结果查询 → 获取 bindId

支付阶段（后续）：
4.7 绑卡支付预下单
    ↓
4.9 绑卡支付

适用场景：

  • 提升绑卡转化率
  • 支持工行等银行 APP 跳转
  • 移动端 H5 绑卡

必填特殊参数：

  • deviceID: 设备标识（64 位）
  • trxTrmInf: 设备信息 JSON
  • merUserRegDt: 用户注册时间（yyyyMMdd）
  • usrLoginMethod: 登录验证方式（5 位位图）

设备信息格式：

{
  "TrxTrmTp": "08",        // 07 电脑 08 手机 10 平板
  "sourceIP": "127.0.0.1", // 客户端 IP
  "deviceSystem": "1"      // 1 安卓 2 IOS 3 其他
}

通用规则

参数规范

| 规则 | 说明 | |------|------| | 时间戳 | yyyyMMddHHmmss（14 位，精确到秒） | | 订单号 | 50 字符以内，同一商户号下唯一 | | 金额 | 单位：元，最小 0.01 元 | | 签名方式 | SM3WITHSM2 |

SM4 加密字段

以下字段需要 SM4 加密，调用 helipay-sm2 技能进行加密：

| 接口 | 需要 SM4 加密的字段 | |------|---------------------| | 4.1 首次支付 | P8_idCardNo, P9_cardNo, P10_year, P11_month, P12_cvv2, P13_phone, ruleJson | | 4.3 确认支付 | P5_validateCode | | 4.4 鉴权绑卡预下单 | P8_idCardNo, P9_cardNo, P10_year, P11_month, P12_cvv2, P13_phone | | 4.6 鉴权绑卡 | P5_validateCode | | 4.7 绑卡支付预下单 | ruleJson（如有） | | 4.9 绑卡支付 | P5_validateCode（如有） | | 4.15 一键绑卡 | P8_idCardNo, P9_phone |

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

签名规则

  1. sign, signatureType参数本身不参与签名，其它参数有标明“不参与签名”或同义的，也不参与签名。
  2. 需要参与签名的参数为空值也需拼接（&P1值&&P3值）即保留连接符号&。
  3. 参数按 &P1值&P2值&P3值... 顺序拼接，若无P1P2开头值，按照文档接口中列表展示的字段顺序拼接，只拼其值。
  4. 中文不需要 URL Encode。

使用 helipay-sm2 技能：将拼接好的签名原文传给 helipay-sm2 技能，获取签名结果。

回调处理

4.10 异步通知接口

通知机制：

  • 订单创建 24 小时内通知
  • 间隔 2 分钟，最多 5 次
  • 成功处理需返回 success（纯文本）

回调参数：

  • rt2_retCode: 0000 表示成功
  • rt9_orderStatus: SUCCESS 表示支付成功
  • rt10_bindId: 绑卡 ID
  • ruleJson: 分账结果（明文，无需解密）

注意事项：

  • 做好幂等处理（可能重复通知）
  • 若前一天通知订单数超过 100 且一条不接收，系统会加入通知限制名单
  • 需返回 success 表示已处理

返回码说明

| 返回码 | 描述 | 处理建议 | |--------|------|----------| | 0000 | 成功 | - | | 0001 | 处理中 | 等待异步结果或查询 | | 8000 | 失败 | 根据返回信息排查 | | 8015 | 短信验证码错误或已过期 | 提示用户重新获取 | | 8017 | 当前银行卡不支持 | 换卡或联系业务确认 | | 8002 | 订单号不唯一 | 更换订单号重试 | | 8999 | 系统异常 | 联系合利宝客服 |

注意事项

  • 分账功能：使用分账前需联系商务开通分账产品
  • 银行支持列表：因支持列表会有变动，最新支持银行列表请联系相关业务人员获取
  • 一键绑卡银行支持：一键绑卡请到 demo 下载页面查看主流银行支持列表
  • 回调地址配置：
    • 交易类通知（支付结果、绑卡结果等）：可通过接口参数 P23_serverCallbackUrl 传递回调地址
    • 解绑通知：需要联系合利宝技术支持配置后台回调地址
  • 敏感信息：不要在日志中明文记录身份证、卡号、手机号等敏感信息

Demo 和资料下载

通过文档 API 获取下载地址：

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/37/8ca9c6e4"

文档内提供：

  • Java/PHP demo 源码下载
  • SKILL 技能文件下载（含完整 demo）
  • 快捷支持银行 + 限额表
  • 银行编码表
  • 支付协议模板

常见对接问题

| 问题 | 解决方案 | |------|----------| | 签名失败 | 检查参数顺序、空值拼接、加密字段是否已加密 | | 订单号重复 | 确保每次请求使用新订单号 | | 回调收不到 | 检查接口参数 P23_serverCallbackUrl 是否配置、网络可达性、是否返回 success | | 银行卡不支持 | 前往 Demo 下载页面 查看最新银行支持列表 | | 短信收不到 | 检查手机号是否为银行预留号，是否超时 |

对接步骤清单

人工准备（对接前完成）

  1. [ ] 登录合利宝商户后台，申请并下载证书（获取 SM2 私钥）
    • 下载 .pfx 格式证书文件
    • 确保证书密码已知（通常在下载时设置或单独提供）
    • 证书密码用于从 .pfx 文件中提取私钥
  2. [ ] 配置回调地址（商户后台设置）

技术对接

  1. [ ] 获取并阅读完整接口文档（使用文档 API）
  2. [ ] 实现签名（使用 helipay-sm2 技能）
  3. [ ] 实现 SM4 字段加密（使用 helipay-sm2 技能）
  4. [ ] 选择支付方式，调通绑卡流程
  5. [ ] 调通支付流程
  6. [ ] 实现回调处理
  7. [ ] 小金额（0.01 元）测试验证

生成时的说明要求

最终回答需要包含：

  • 接口字段说明：列出请求参数（P1~P28）、返回参数的完整说明，明确哪些字段需要 SM4 加密、哪些字段参与签名。
  • 签名源串拼接规则：按 &P1 值&P2 值&P3 值... 顺序拼接，空值也需拼接，sign 参数本身不参与签名。
  • SM4 加密字段清单：明确告知用户哪些字段需要调用 helipay-sm2 技能进行加密（身份证、卡号、手机号、CVV2、有效期等）。
  • 代码示例：提供完整的请求参数组装、签名、调用示例（Java/Python 等，根据用户要求）。
  • 配合 helipay-sm2 技能使用：
    • 签名：将拼接好的签名源串传给 helipay-sm2 技能，获取 SM3withSM2 签名结果
    • SM4 加密：将需要加密的敏感字段明文传给 helipay-sm2 技能，获取密文填入请求参数
    • SM4 解密（回调处理）：将密文传给 helipay-sm2 技能进行解密
  • JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）
  • 明确说明：本技能只处理合利宝快捷支付接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
  • 提醒：签名源串的字段顺序、排除字段、证书格式必须与合利宝官方文档一致；如有自定义分账、权益类字段，需联系业务确认。