开发者接入指南:把稳付pay接入你的产品
你的网站、发卡平台或应用负责创建业务订单与交付商品,稳付pay负责支付通道对接和支付结果通知。本指南按实际接入顺序说明需要配置什么、调用什么,以及什么时候可以把订单改为已支付。
文章目录
先确认你要接入的服务
本组文档说明已开通支付通道的代收下单、订单查询和支付成功通知。代付暂未开放。可用通道、正式网关、结算安排和商户权限,由稳付pay技术人员在开通时与你确认。
代收后的结算安排,与客户直接支付到商户自有 USDT 钱包的链上监控服务,是不同的业务路径。本组代收接口不代表 USDT 链上直收接口。
本文网址、订单号和凭据均为示例。请先完成技术对接,取得属于你自己的配置,不要把演示参数直接用于生产。
第一步:申请商户配置
| 配置项 | 使用位置 | 需要确认的内容 |
|---|---|---|
API_BASE_URL | 商户服务端 | 分配的实际网关;本文以 https://gateway.example.com 示意。 |
MERCHANT_ID | 商户服务端 | 你的商户号,请求字段名为 mchId。 |
MD5_SECRET | 环境变量或密钥管理 | 下单和查单使用的 API 密钥。 |
CALLBACK_SECRET | 服务端密钥管理 | 单独配置的回调密钥;未配置时回退使用 API 密钥。 |
wayCode | 支付方式映射 | 该商户实际开通的真实通道或聚合编码。 |
notifyUrl | 公开 HTTPS 后端接口 | 例如 https://merchant.example.com/pay/notify。 |
密钥只保存在后端,前端只取得业务订单和允许展示的支付链接。测试与正式配置分别保存;日志应对密钥及签名原文中的密钥部分脱敏。
第二步:接通完整支付流程
- 创建业务订单服务端确定商品、金额、币种和唯一商户订单号,保存待支付记录。
- 服务端签名下单生成当前毫秒时间戳,计算签名,请求代收创建接口。
- 展示有效支付链接检查实际返回的 payUrl,再引导付款;没有链接时进入查询或异常处理。
- 核验成功通知后端验签,核对商户、订单、币种与金额,不依靠浏览器跳转判断到账。
- 幂等更新与交付支付状态持久化,使用唯一交付记录,避免重复发卡、充值或发货。
- 查单与核对对超时、通知遗漏和长时间待支付的订单主动查询,保留处理记录。
第三步:在产品中准备四个接入位置
| 系统位置 | 接入职责 | 保留记录 |
|---|---|---|
| 下单服务 | 校验业务订单、签名并调用创建接口。 | 商户订单号、金额分、币种、平台订单号。 |
| 支付展示页 | 展示真实支付链接和本地状态。 | 关联订单与客户访问权限。 |
| 异步通知接口 | 验签、核对、幂等持久化成功结果。 | 通知摘要、校验结果和接收时间。 |
| 查单任务 | 补齐未知结果,进入同一交付流程。 | 查询结果、次数和最后核对时间。 |
使用现成发卡平台时,把这些逻辑接入其支付插件或服务端扩展。确认平台能保存独立商户订单号、按原始参数验签,并支持幂等交付;只增加一个跳转链接还不算完成对接。
上线前的接入验收清单
- 完成约定的测试订单,下单金额按分传入,能关联正确的平台订单与支付入口。
- 正确签名可通过,缺字段、篡改金额和错误签名能够被识别与记录。
- 用户关闭浏览器后,服务端仍能通过通知或查单更新状态。
- 重复通知、通知与查单同时成功时,均只交付一次。
- 下单超时先查原订单,不盲目换订单号重下;未知结果保留待核实。
- 支付成功但交付失败可安全重试,支付与商品交付均有记录。
- 通知接口可被公网访问,密钥不进入页面源码、公开附件和日志。
测试额度、通道权限和异常处理由技术人员与你确认。需要协助时,提供脱敏订单号、请求时间和错误摘要即可,不要在截图中展示密钥。
继续完成接口接入
依次阅读代收下单与查询、请求签名规则和回调验签与幂等交付。技术人员会按你的开发框架、发卡系统和已开通通道提供接入协助。
本文依据稳付pay接入规范整理。示例用于解释调用位置和参数结构,正式联调使用分配给你的配置。