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

合利宝接口对接_扫码产品V001

合利宝接口对接，扫码产品接口

personAuthor: LuckyKhubModelScope
downloadDownload package

合利宝扫码支付接口

概述

合利宝扫码支付支持主扫、被扫、公众号、小程序、H5、APP、银联云闪付等多种支付方式。

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

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/14/c7410407"

接口地址

| 环境 | 地址 | |------|------| | 测试环境 | https://test.trx.helipay.com/trx/app/interface.action | | 生产环境 | https://pay.trx.helipay.com/trx/app/interface.action | | 用户信息查询接口 | https://pay.trx.helipay.com/trx/userinfo/interface.action |

测试环境也是真实交易，请用小金额测试！

请求通用规则

| 项目 | 说明 | |------|------| | 请求方法 | POST | | 请求格式 | application/x-www-form-urlencoded（form 表单） | | 字符编码 | UTF-8 | | 接口识别 | 通过请求地址 + P1_bizType 字段值判定是哪个接口 |

支付方式路由

| 场景 | P1_bizType | P4_payType | 说明 | |------|------------|------------|------| | 主扫支付 | AppPay | SCAN | 商户生成二维码，用户扫码 | | 被扫支付 | AppPay | SWIPE | 商户扫描用户付款码（POS/扫码枪） | | 公众号支付 | AppPayPublic | PUBLIC | 微信/支付宝公众号内支付 | | 小程序支付 | AppPayApplet | APPLET | 微信/支付宝小程序 | | H5(WAP) 支付 | AppPayWap | WAP | 手机浏览器网页支付 | | APP 支付 | AppPaySdk | SDK | 原生 APP 内支付 | | 银联云闪付 | AppPayPublic | PUBLIC | 银联二维码支付 | | 订单查询 | AppPayQuery | - | 查询支付状态 | | 订单退款 | AppPayRefund | - | 退款处理 | | 退款查询 | AppPayRefundQuery | - | 查询退款状态 | | 订单撤销 | AppPayReverse | - | 撤销当日订单 |

回调通知

| 项目 | 说明 | |------|------| | 通知方法 | POST | | 通知格式 | application/x-www-form-urlencoded（form 表单） | | 回调地址 | 不能带重定向参数 | | 响应要求 | 处理成功后返回纯文本 success | | 通知机制 | 订单创建 24 小时内通知，间隔 2 分钟，最多 5 次 |

参数规范

| 规则 | 说明 | |------|------| | 时间戳 | yyyyMMddHHmmss（14 位，精确到秒） | | 订单号 | 50 字符以内，同一商户号下唯一 | | 金额 | 单位：元，最小 0.01 元 | | IP 地址 | IPv4 格式，不要传其他内容 | | 签名方式 | SM3WITHSM2 或 MD5 |

签名规则

固定不参与签名的字段（所有接口通用）： | 字段名 | 变量名 | |--------|--------| | 签名结果 | sign | | 加密密钥 | encryptionKey | | 签名方式 | signatureType | | 特殊业务参数 | ruleJson、splitBillType、P15_subMerchantId 等文档明确标注"排除签名"的字段 |

如何判断其他字段是否参与签名：

  • 每个接口的 NEED_SIGN_PARAMS 常量定义了需要参与签名的固定参数集合
  • 只有 NEED_SIGN_PARAMS 中列出的参数才参与签名，其他参数即使传了也不参与签名
  • 空值字段也要参与签名（保留连接符）

拼接规则：

  1. 参与签名的字段按 NEED_SIGN_PARAMS 定义的顺序拼接
  2. 字段之间用 & 连接，格式为：&P1值&P2值&P3值...
  3. 空值字段也要保留连接符：例如 &AppPay&&C1800000002&SCAN 表示 P2 不传值但保留位置
  4. 中文不需要 URL Encode
  5. 尾部处理根据签名方式区分：
    • MD5：尾部追加 &+MD5 签名秘钥
    • SM3WITHSM2（国密）：不追加任何内容，直接结束

签名方式对比： | 签名方式 | signatureType | 拼接结果 | |----------|---------------|----------| | MD5 | MD5 | &P1值&P2值...&md5Key | | SM3WITHSM2（国密） | SM3WITHSM2 | &P1值&P2值... |

签名结果 URL 编码：最终提交的 form body 中 sign 值必须是 URL 编码后的，但编码方式因语言而异：

| 语言 | 做法 | 注意 | |------|------|------| | Java | 手工拼 form body 时用 URLEncoder.encode(sign, "UTF-8") 主动编码 | 必须手动编码 | | PHP | 用 http_build_query() 组装参数，不要手动 urlencode() | http_build_query 已自动编码，手动再编会导致双重编码（%→%25），服务端验签失败 |

SM4/3DES 加密字段

| 接口 | 需要加密的字段 | |------|---------------| | 所有接口 | ruleJson（分账规则串，如有）、marketingRule（营销规则串，如有） | | 4.1/4.15 | P8_idCardNo、P9_phone（实名信息，如有） |

注意：MD5 签名方式时使用 3DES 加密，SM3WITHSM2 签名方式时使用 SM4 加密。

注意事项

  • 各接口具体的请求参数（P1~P28 等）、返回参数、返回码以最新文档为准，请用上方 curl 命令获取。
  • 主扫下单返回码 0000 仅代表下单成功，支付结果以回调或查询为准。
  • 被扫接口需要同时判断返回码和订单状态，必要时主动查询。
  • 退款接口返回 0001 表示受理成功，退款结果以退款回调和查询为准。
  • 回调地址必须为外网可访问的 URL，不能携带参数。
  • 敏感信息保护：不要在日志中明文记录身份证、卡号、手机号等。
  • 做好回调幂等处理（可能重复通知），订单状态以回调为准。

生成时的说明要求

最终回答需要包含：

  • 接口请求方式：明确告知接口是 POST form 表单格式（application/x-www-form-urlencoded），不是 JSON；接口通过请求地址和P1_bizType 字段值来判定是哪个接口。
  • 回调通知格式：明确告知回调地址不能带重定向参数，回调数据为 form 表单格式（不是 JSON），需要从 POST body 解析 form 参数，处理成功后返回纯文本 success。
  • 接口字段说明：列出请求参数、返回参数的完整说明（以最新文档为准），明确哪些字段参与签名（NEED_SIGN_PARAMS 中定义的字段）、哪些字段需要 SM4/3DES 加密。
  • 签名源串拼接规则：按 &P1值&P2值&P3值... 顺序拼接（仅 NEED_SIGN_PARAMS 中的字段），空值也需拼接保留连接符。sign、encryptionKey、signatureType 不参与签名。尾部处理：MD5 签名方式追加 &+MD5 签名秘钥，SM3WITHSM2 国密方式不追加任何内容。两种方式二选一。签名结果需 URL 编码，但 PHP 用 http_build_query() 时不要手动 urlencode()（会自动编码），Java 手工拼 form body 时需主动 URLEncoder.encode()。
  • 加密字段清单：明确告知用户 ruleJson、marketingRule、P8_idCardNo、P9_phone 等敏感字段需要加密。MD5 签名方式时使用 3DES 加密，SM3WITHSM2 签名方式时使用 SM4 加密。
  • 代码示例：提供完整的请求参数组装、签名、调用示例（Java/Python 等，根据用户要求）。
  • 配合 helipay-sm2 技能使用：
    • 签名：将拼接好的签名源串传给 helipay-sm2 技能。MD5 方式源串为 &P1值&P2值...&md5Key，SM3WITHSM2 国密方式源串为 &P1值&P2值...（不追加 md5Key）。
    • 加密：将需要加密的敏感字段明文传给 helipay-sm2 技能，获取密文填入请求参数。
    • 解密（回调处理）：将密文传给 helipay-sm2 技能进行解密。
  • JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
  • 明确说明：本技能只处理合利宝扫码支付接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
  • 提醒：签名源串的字段顺序、排除字段、证书格式必须与合利宝官方文档一致；主扫/被扫/公众号/H5 支付等不同支付方式的参数要求不同，请严格按对应接口文档组装。
  • 金额单位：元（不是分），最小金额 0.01 元。