线下二维码支付
约 1361 字大约 5 分钟
2025-06-24
主要参与方
PingPongCheckout的线下二维码支付解决方案实现了SAAS收银机与POS设备通过云端服务进行通信，完成支付、查询、退款等交易流程。该方案采用REST API方式，生成二维码供消费者使用移动支付工具完成支付。
- SAAS收银机：发起交易请求，展示二维码，接收交易结果
- PingPong收单服务：处理请求，生成二维码，通知交易结果
- 消费者移动设备：扫描二维码完成支付
API 清单
支付流程
发起支付请求
SAAS收银机向PingPong收单服务发送统一下单支付请求(unifiedPay) 请求中必须包含cashierDeviceId参数标识收银机自身 指定paymentMethod参数为相应的二维码支付方式
注意
请求参数中的timeExpire表示二维码的有效期，可设置1分钟到3天。若不设置，默认为3天。 为提高用户体验，建议设置合理的二维码超时时间，通常零售场景建议设置为5分钟。
生成二维码
PingPong收单服务接收请求并验证签名 生成支付二维码，返回qrCode和qrUrl参数 同时返回qrCodeExpired参数表示二维码过期时间
展示二维码
SAAS收银机接收响应，将二维码展示给消费者 消费者使用移动支付工具（如支付宝、微信等）扫描二维码完成支付
支付结果查询
初始响应状态通常为PROCESSING SAAS收银机需通过查询API(query)轮询订单状态 或等待PingPong收单服务通过notificationUrl推送支付结果
重要提示
收单服务返回的初始状态为PROCESSING，只表示二维码生成成功，不代表支付完成。 SAAS收银机应实施轮询机制，建议间隔3-5秒查询一次，直到获取最终支付结果。
退款流程
发起退款请求
SAAS收银机向收单服务发送退款请求(refund) 请求中包含原交易信息和退款金额 必须包含cashierDeviceId参数标识收银机自身
退款处理
收单服务验证请求并处理退款操作 退款结果可能不会立即返回，初始可能为ACCEPT_SUCCESS或PROCESSING状态
结果查询
SAAS收银机通过退款查询API(refund/query)获取最终退款结果 轮询查询直到退款状态变为SUCCESS或FAILED
退款建议
对于二维码支付的退款，建议在系统中保留原交易的merchantTransactionId，以便在退款时快速关联原交易。