拉卡拉分账系统API完整对接全流程（注册认证→文档 SDK 下载→规则配置→回调开发→沙箱测试→生产上线）

依托央行持牌资质（牌照 Z2002511000017），整套对接分为商务资质开通、开发准备、后台配置、代码开发、沙箱联调、灰度上线6 大环节，完整可落地操作步骤如下：

一、第一步：企业注册 + 资质认证，开通分账 API 权限

1. 官方注册入口

拉卡拉正规开发者平台：拉卡拉开放平台 o.lakala.com，禁止第三方仿站注册拉卡拉开放...

2. 必备企业资质材料

1. 营业执照（经营范围含电商 / 零售 / 供应链 / 本地生活等经营类目）
2. 法人身份证正反面、对公结算账户
3. 电商平台额外提供：ICP 备案证书；教培 / 医美 / 食品补充行业许可证
4. 签署《分账服务协议》《开放平台 API 接入协议》

3. 审核与核心参数下发

1. 小微连锁 / 小型平台：AI 自动审核 5 分钟通过；大型集团人工审核 1–3 个工作日
2. 审核通过后后台获取核心密钥（对接必备）：
   • appId 应用 ID、mchId 商户号
   • RSA 商户私钥、拉卡拉平台公钥（双重签名防篡改）
   • 沙箱测试账号、测试资金额度

4. 开通分账专属权限

后台勾选「订单实时分账、多级链式分账、异步回调、批量分账查询」接口权限，未勾选接口调用直接返回无权限报错

二、第二步：下载官方 API 文档 + 多语言 SDK，搭建开发环境

1. 文档 & SDK 下载位置（开放平台资源中心）

1. 《分账系统 API 开发文档》：包含统一下单、创建分账、分账查询、退款分账、回调规范、返回错误码全集
2. 官方原生 SDK（封装签名、验签、HTTP 请求，省去自研加密逻辑）： Java / PHP / Python /.NET/ Go 全主流技术栈配套 Demo 示例拉卡拉开放...

2. 环境区分（严格隔离，禁止混用）

• 沙箱测试地址（联调专用）：https://test.wsmsd.cn/sit
• 生产正式地址（上线后切换）：https://s2.lakala.com

3. 服务器硬性要求

1. 对外接口必须支持 HTTPS（回调地址强制 https，http 无法接收通知）
2. 服务器出口 IP 添加至拉卡拉后台白名单，防止接口请求拦截
3. PHP≥7.0、Java8+，支持 JSON / 表单 POST 请求

三、第三步：后台配置分账基础规则、分账方白名单

1. 录入分账接收方白名单（前置强制操作）

所有供应商、门店、渠道、分销商必须先录入后台白名单，填写： 收款人姓名、一类银行卡号、开户行、身份证号；未录入白名单的账户无法接收分账资金

2. 配置四大分账计算规则（两种配置方式）

方式 A：后台可视化预设规则（推荐中小平台）

后台创建固定规则模板，下单接口仅传规则 ID即可自动拆分，支持： 比例分账、固定金额扣费、阶梯分润、混合拆分；支持十级多层级链式分账

方式 B：API 动态传参（大型多变业务）

每笔订单独立传递分账数组，灵活修改比例 / 金额，无需后台提前建模板

3. 结算周期配置

可选两种分账时效，后台一键切换：

1. T+1 批量分账：免费，次日统一清算分拨
2. D0 实时分账：支付完成瞬间空中拆分，收取 0.1%–0.3% 分账加急服务费

4. 关键全局配置项

1. 分账失败处理规则：原路退回平台备付金 / 冻结待人工复核
2. 对账文件自动推送邮箱 / API 下载
3. 交易限额、单笔最大分账接收方数量（单笔最多 50 个分账账户）

四、第四步：异步回调地址开发配置（核心，保障订单状态同步）

1. 回调地址规范

1. 公网可访问 HTTPS 接口，示例：https://你的域名/api/lakala/sharing_notify
2. 同一商户可配置支付结果回调、分账结果独立回调两个地址，分开接收通知

2. 回调处理标准开发逻辑（固定流程）

1. 接收拉卡拉 POST 推送的全部参数、签名串
2. 使用拉卡拉公钥验签，签名不通过直接丢弃请求，避免伪造攻击
3. 解析订单号、总金额、各分账方金额、分账状态（成功 / 失败）、清算时间
4. 数据库开启事务，同步更新本地订单、分账记录表状态
5. 处理完成必须返回字符串 success；返回 fail / 无返回拉卡拉会持续重推 8 次回调

3. 数据库表必备字段（分账记录表）

订单号、总金额、各分账方 ID、分账金额、分账状态、回调时间、清算流水号

五、第五步：代码开发核心接口调用逻辑（标准流程）

完整业务链路：统一下单 → 支付完成 → 自动分账 → 回调推送结果 → 对账查询

核心接口 1：统一下单（携带分账参数）

接口路径：/api/v3/pay/unifiedorder 关键新增分账参数二选一：

1. 传入后台预设rule_id规则 ID（简易模式）
2. 传入receivers分账数组（动态自定义模式，包含分账方 ID、比例 / 固定金额）

核心接口 2：分账结果主动查询（兜底补偿）

接口路径：/profit-sharing/v1/query 业务场景：回调丢失、服务器宕机，定时任务主动拉取订单分账状态，修复本地数据不一致

核心接口 3：退款同步分账撤销

发起订单退款时，接口自动反向扣回已分账资金，原路退回各方账户

代码通用流程（SDK 标准模板）

1. 初始化 SDK，填入 appId、商户私钥、环境域名
2. 组装业务请求参数，自动生成 RSA 签名
3. HTTP POST 请求拉卡拉接口
4. 响应验签，解析返回 JSON 数据，处理成功 / 异常状态

六、第六步：沙箱环境完整测试（必须全覆盖场景，不测试禁止上线）

1. 沙箱模拟测试场景清单

1. 正常订单：比例分账、固定金额、阶梯、混合拆分 4 类规则全测
2. 多接收方十级链式分账，验证各账户金额计算精准度
3. D0 实时分账、T+1 批量分账两种时效测试
4. 部分退款、全额退款，校验分账资金回冲逻辑
5. 分账方账户异常（银行卡失效），验证失败资金回流机制
6. 回调异常：关闭本地接口，验证拉卡拉重试推送逻辑

2. 测试验收标准

1. 分账计算金额无误差，和后台规则完全匹配
2. 回调接收稳定，签名校验无报错
3. 所有异常返回码正常捕获，系统不崩溃、不丢单
4. SDK 无加密报错、证书校验正常

3. 测试通过凭证

整理测试日志、分账流水截图，提交拉卡拉技术运营审核，获取上线开通许可

七、第七步：切换生产环境，灰度灰度全量上线

1. 切换生产环境操作

1. 代码内替换环境地址为生产域名、更换正式商户私钥 / 证书
2. 后台更新生产环境回调地址、服务器 IP 白名单
3. 关闭沙箱测试账号参数，删除测试环境依赖代码

2. 灰度上线流程（降低资金风险）

1. 少量测试订单真实支付，人工核对分账到账流水
2. 灰度 1–2 天，监控分账成功率、回调延迟、对账差错
3. 无异常后全量开放所有订单自动分账

3. 上线后运维配套能力

1. API 对账接口每日自动同步分账流水，对接企业 ERP / 财务系统
2. 后台实时查看分账失败订单，支持人工重分账
3. 7×24 技术支持：开放平台工单 + 95016 专线对接技术人员

八、对接周期参考

1. 资质认证：0.5–3 天
2. 环境搭建 + SDK 开发：1–2 天
3. 回调接口 + 业务逻辑开发：1 天
4. 沙箱全场景联调：0.5–1 天 中小型平台最快 3 天完整上线；大型集团定制化对接 5–7 天

九、高频避坑要点

1. 回调地址不能用内网地址，必须公网 HTTPS；80/443 端口开放，防火墙放行拉卡拉服务器 IP
2. 分账接收方必须提前录入白名单，线下新增分销商需后台录入后才能参与分润
3. 签名密钥严禁明文写死在前端、客户端，仅后端服务保存私钥
4. 沙箱测试资金为模拟金额，无真实资金流转；上线前必须走完全量异常场景测试
5. 禁止绕过 API 后台手动分账，所有资金拆分留接口流水，满足税务、监管审计三流合一要求