QRPH 商户 API 接入怎么做?接口、验签与生产切换流程(2026)
QRPH 商户 API 接入的核心链路是:申请 MID 与密钥 → 沙箱环境联调下单/回调/对账 → 完成验签与幂等设计 → 通过收单方或网关审核 → 灰度切换到生产。走通这条链,QRPH 收款才能稳定跑起来。
一、API 接入前你要拿到的东西
动手写代码前,先确认三样齐:合规通过的商户号(MID)、生产与沙箱两套密钥对、收单方或持牌四方发的接入文档。文档通常包含域名、加签算法、字段字典、回调格式与对账文件规范。缺一样都写不下去。
二、主要接口类型
- 下单接口:生成 QRPH 动态码或返回可拉起钱包 App 的 URL Scheme
- 查询接口:按订单号或平台流水号查真实交易状态,兜底回调丢失
- 回调通知:异步推送支付结果,需要商户返回约定应答体
- 退款接口:全额或部分退款,退款结果同样通过异步回调
- 对账文件:按日下载,用于财务对账与差错核验
三、验签规范:被打回最多的地方
- 按文档约定拼接原始串(参数字典序、去空、注意大小写)
- 使用商户私钥做 RSA/SM2 签名,或按 HMAC-SHA256 计算摘要
- 请求头或 body 中携带签名字段与商户号
- 收到回调后先用平台公钥验签,验签通过再解析业务字段
- 回调处理必须幂等,同一订单多次通知要能被识别
常见坑:签名字段大小写混用、金额取到浮点数、时间戳误用毫秒而非秒、忘记 URL Encode。任一处出错都会导致联调死循环。
四、通过 SMARTPAY 快速接入(推荐路径)
接口协议、验签、回调这些工程细节,没有专用文档与联调支持,商户团队很容易踩坑。走持牌四方网关的价值在于统一 API 抽象层:一套接口打通 QRPH 与钱包/银行通道,联调工程师全程陪跑。可先读 菲律宾支付 API 怎么对接,或从 QRPH 商户开通条件 反推资料清单。
SMARTPAY 是持 BSP OPS/EMI 牌照的独立支付网关,提供 QRPH / GCash / Maya 等通道 API 对接服务,非 QRPH 官方发行方。
五、常见问题
沙箱和生产的差异在哪?
沙箱账号只在测试链路流转,金额、渠道、风控都是模拟,不会真实扣款。生产切换后进入真实清算网络,任何字段错误都会引起资金问题,建议先在沙箱把异常场景(超时、退款、并发下单)跑一遍。
回调失败或延迟怎么办?
回调可能因网络抖动丢失或超时,商户须实现主动查询兜底:回调迟迟不到,按订单号轮询查询接口。回调处理要幂等,重复通知不要重复发货或入账。
生产切换需要审批吗?
需要。收单方或网关会审核联调记录、异常处理、日志留存、对账一致性,通过后才开放生产密钥与真实通道。建议先在灰度阶段小额验证一段时间,再逐步放量。
密钥泄露了怎么办?
立即后台重置密钥,联系收单方冻结旧密钥调用权限,并核查最近的交易与回调日志。日常密钥应放在 KMS 或环境变量里,严禁写死到代码仓库。
六、快速开通
想快速接入合规支付通道,联系 SMARTPAY:📩 [email protected] | Telegram @LouisSMARTPAY