开发者文档

开发者接入指南:把稳付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。

密钥只保存在后端,前端只取得业务订单和允许展示的支付链接。测试与正式配置分别保存;日志应对密钥及签名原文中的密钥部分脱敏。

第二步:接通完整支付流程

  1. 创建业务订单服务端确定商品、金额、币种和唯一商户订单号,保存待支付记录。
  2. 服务端签名下单生成当前毫秒时间戳,计算签名,请求代收创建接口。
  3. 展示有效支付链接检查实际返回的 payUrl,再引导付款;没有链接时进入查询或异常处理。
  4. 核验成功通知后端验签,核对商户、订单、币种与金额,不依靠浏览器跳转判断到账。
  5. 幂等更新与交付支付状态持久化,使用唯一交付记录,避免重复发卡、充值或发货。
  6. 查单与核对对超时、通知遗漏和长时间待支付的订单主动查询,保留处理记录。
下单成功不等于付款成功;交付应由可信的服务端支付结果触发。

第三步:在产品中准备四个接入位置

系统位置接入职责保留记录
下单服务校验业务订单、签名并调用创建接口。商户订单号、金额分、币种、平台订单号。
支付展示页展示真实支付链接和本地状态。关联订单与客户访问权限。
异步通知接口验签、核对、幂等持久化成功结果。通知摘要、校验结果和接收时间。
查单任务补齐未知结果,进入同一交付流程。查询结果、次数和最后核对时间。

使用现成发卡平台时,把这些逻辑接入其支付插件或服务端扩展。确认平台能保存独立商户订单号、按原始参数验签,并支持幂等交付;只增加一个跳转链接还不算完成对接。

上线前的接入验收清单

  • 完成约定的测试订单,下单金额按分传入,能关联正确的平台订单与支付入口。
  • 正确签名可通过,缺字段、篡改金额和错误签名能够被识别与记录。
  • 用户关闭浏览器后,服务端仍能通过通知或查单更新状态。
  • 重复通知、通知与查单同时成功时,均只交付一次。
  • 下单超时先查原订单,不盲目换订单号重下;未知结果保留待核实。
  • 支付成功但交付失败可安全重试,支付与商品交付均有记录。
  • 通知接口可被公网访问,密钥不进入页面源码、公开附件和日志。

测试额度、通道权限和异常处理由技术人员与你确认。需要协助时,提供脱敏订单号、请求时间和错误摘要即可,不要在截图中展示密钥。

继续完成接口接入

依次阅读代收下单与查询、请求签名规则和回调验签与幂等交付。技术人员会按你的开发框架、发卡系统和已开通通道提供接入协助。

本文依据稳付pay接入规范整理。示例用于解释调用位置和参数结构,正式联调使用分配给你的配置。

按你的业务场景确认接入

说明商品、订单量、支付方式与结算需求,逐项确认接口、资金路径和异常处理。

联系稳付pay ↗