拉卡拉API支付接口｜沙箱测试环境上线前完整联调流程
一、沙箱环境基础信息（环境完全隔离，无真实资金）
1. 双环境域名隔离（严禁混用密钥）
-
沙箱测试环境（SIT） 网关域名：
https://test.wsmsd.cn/sit/i.lakala.c... 核心接口统一前缀：/api/v3/退款 / 下单 / 查询沙箱地址：https://test.wsmsd.cn/sit/labs/txn/xxx -
生产正式环境 网关域名：
https://s2.lakala.com/
2. 沙箱核心资源（企业资质审核通过后开放平台发放）
-
沙箱专属：
mercId商户号、termNo终端号、独立 RSA 签名密钥对（沙箱 / 生产密钥完全不互通） - 测试虚拟支付账号、测试银行卡、测试条码授权码
- 官方多语言 SDK：Java/PHP/Python/Go，内置签名工具、Demo 示例
-
测试公钥获取地址：
https://test.wsmsd.cn/sit/gw/pubcerts?appId=xxx
3. 沙箱核心规则
- 所有交易为虚拟资金，不扣真实货款、无实际结算；
- 支持微信 / 支付宝 / 云闪付 / H5 / 小程序 / APP 全渠道模拟支付；
- 支持钱账通分账 API 沙箱联调，模拟多级自动拆分；
- 沙箱数据每日凌晨自动清理，不留存测试订单；
- 异步回调地址仅允许公网可访问 HTTPS 域名，本地localhost无法接收通知。
二、前置准备：企业资质认证 + 开放平台配置（联调前必完成）
1. 资质材料（个人小微无法开通 API）
营业执照、法人身份证、对公基本存款账户、ICP 备案（线上商城 / 小程序）、特殊行业经营许可证；钱账通分账额外提供分账合作方清单、盖章分账授权书。
2. 开放平台后台 4 项核心配置
- 创建支付应用：区分小程序 / APP/H5 / 线下 POS 归集渠道，开通聚合支付、退款、订单查询、分账接口权限；
- 配置异步回调 notify_url：公网 HTTPS 地址，支付成功、退款、分账完成会推送 JSON 报文，必须实现签名校验、幂等处理；
- 服务器 IP 白名单：将拉卡拉官方出口 IP 加入防火墙白名单，防止接口拦截；
- 渠道配套配置：微信小程序配置支付授权目录、业务域名；APP 配置应用签名包名。
3. 开发环境前置准备
-
封装 SHA256withRSA 签名 / 验签工具（90% 调试报错源于签名格式错误）拉卡拉开放...
-
拼接规则：
appId\n序列号\n时间戳\n随机串\n请求Body\n，末尾必须保留换行符； -
金额强制保留 2 位小数（
100.00，禁止100.0）
-
拼接规则：
-
订单号全局唯一：商户侧
out_trade_no全局不可重复； - 异常重试机制：接口超时、回调重复推送幂等去重逻辑。
三、第一阶段：单接口独立调试（沙箱基础功能通跑）
按顺序调试核心基础接口，单接口无报错再走完整支付链路：
1. 统一下单接口 /api/v3/pay/unifiedorder（核心）
- 入参校验：商户号、终端号、订单号、金额、渠道类型（JSAPI/APP/MWEB/NATIVE）、回调地址；
- 分账场景追加分账接收方、分账比例参数，实现支付即自动拆分；
-
预期返回：
prepay_id预支付凭证、收银台跳转链接；返回码00代表调用成功。
2. 订单查询接口 /labs/txn/labs_order_query
- 场景：用户未触发回调、网络中断，商户主动轮询同步订单状态；
- 校验：支付金额、手续费、分账金额与下单参数完全匹配。
3. 全额 / 部分退款接口 /labs/txn/labs_order_refund
- 约束：退款单号唯一，不可重复退款；仅支持已支付未全额退款订单；
- 逆向分账校验：退款后同步冲正各分账方资金。
4. 关单接口 /labs/txn/labs_order_close
用户放弃支付、超时未付款主动关闭订单，释放预支付凭证。
5. 钱账通分账扩展接口（平台 / 连锁必备）
分账接收方新增、分账结果查询、批量分润逆向冲正。
四、第二阶段：端到端完整业务链路联调（核心验收环节）
链路 1：标准支付闭环（小程序 / H5/APP 通用时序）
- 用户下单提交 → 商户服务端调用沙箱统一下单 API；
- 拉卡拉沙箱返回支付凭证，前端拉起虚拟收银台；
- 使用测试账号完成模拟支付；
- 拉卡拉主动推送异步回调至商户 notify 地址；
- 商户服务端验签成功，更新订单为「已支付」；
- 商户后台主动调用查询接口二次核对订单状态，防止回调丢失。
链路 2：支付 + 自动空中分账闭环
- 下单时携带多级分账规则（总部 / 门店 / 供应商）；
- 模拟支付成功，沙箱按预设比例自动拆分虚拟资金；
- 回调同步分账明细，校验各方拆分金额、手续费计算；
- 模拟部分退款，验证分账资金同步冲正。
链路 3：退款完整链路
- 传入原订单号、退款金额、商户退款单号；
- 沙箱返回退款成功；
- 接收退款异步回调，商户订单同步标记「已退款」；
- 查询接口核对原订单剩余未退金额。
五、第三阶段：全场景覆盖测试用例清单（上线前必须 100% 通过）
1. 基础功能场景
- 小额支付（0.01 元）、标准金额（100 元）、大额（99999.99 元）；
- 微信、支付宝、云闪付多渠道分别测试；
- 正常支付、用户中途退出取消支付；
- 同一订单重复发起下单，拦截重复订单；
- 订单超时自动关单、手动主动关单。
2. 退款场景
- 全额退款；
- 部分退款（分多次小额退款）；
- 重复退款（沙箱返回错误码拦截）；
- 已关单 / 未支付订单发起退款，返回合法报错。
3. 分账专属场景
- 单一比例分账、固定金额分账、阶梯分账、多级链式分账；
- 单笔订单最多 50 个收款方拆分；
- 分账后退款，各方资金同步扣减；
- 分账比例 0%–100% 边界校验。
4. 异常 & 边界场景（高风险，极易上线踩坑）
- 网络超时、接口 502/503 服务不可用，重试逻辑无重复下单；
- 异步回调重复推送，幂等处理不重复更新订单；
- 参数缺失、商户号错误、签名错误，返回标准错误码；
- 金额格式错误（整数、一位小数、负数），接口拦截报错；
- 超长订单号、特殊字符订单号兼容性校验。
5. 安全校验场景
- 回调报文篡改，验签失败拒绝处理；
- 沙箱密钥泄露模拟，接口拒绝访问；
- 敏感信息全报文加密传输合规校验。
六、第四阶段：对账、回调、性能稳定性测试
- 对账文件校验 沙箱每日生成 T+1 交易 / 分账明细，自动推送 SFTP；核对订单、手续费、分账金额与后台一致；
- 回调稳定性 连续批量测试 20 笔订单，100% 收到回调，无丢单、延迟推送；
- 并发压力简易测试 JMeter 模拟 50–200 并发下单，接口无超时、重复支付、数据错乱；
- 长时间稳定测试 连续 2 小时循环支付、退款、分账，无内存泄漏、连接池耗尽。
七、第五阶段：沙箱自测验收标准（全部达标才可申请上线）
- 所有接口正常流程、异常场景测试用例100% 通过，无严重 / 阻断级缺陷；
- 异步回调验签、幂等逻辑稳定，订单状态与拉卡拉沙箱后台完全一致；
- 分账金额、手续费计算无偏差，逆向退款冲正逻辑正常；
- 签名、报文格式、金额精度完全符合文档规范，无验签报错；
- 对账文件明细完整，可直接用于财务核算；
- 完整输出《沙箱 API 联调测试报告》，包含测试范围、用例、缺陷修复记录。
八、第六阶段：提交上线申请，切换生产环境
- 开放平台提交上线验收工单，上传沙箱测试报告，技术审核 1 个工作日；
- 审核通过，发放生产环境商户号、生产 RSA 密钥、生产网关地址；
-
代码配置切换（关键，避免线上故障）：
-
网关域名：测试
test.wsmsd.cn→ 生产s2.lakala.com - 替换沙箱商户号、终端号、RSA 密钥对（两套密钥严禁混用）
- 回调地址切换为线上正式业务域名；
-
网关域名：测试
- 灰度小流量试运行：先放 10% 真实订单观察 24 小时，监控支付、回调、分账、退款稳定性；
- 全量上线，开启正式收款、自动分账能力。
九、上线后运维配套能力
- 每日自动推送 T+1 生产对账文件，线上线下 POS 资金统一归集对账；
- 全量支付、分账记录区块链存证，带官方电子回单用于审计报税；
- 技术支持通道：开放平台工单、95016 技术专线、专属对接人；
- 异常订单自动预警，支持批量查询、批量退款、批量分账。
十、完整联调周期参考
- 资质认证 + 后台配置：1–3 个工作日
- 单接口独立开发调试：2–4 个工作日
- 全链路 + 全场景沙箱测试：2–3 个工作日
- 上线审核 + 灰度试运行：1–2 个工作日 标准总周期：5–12 天；成熟商城 ERP 可缩短至 3 天
