拉卡拉分账系统API接口文档：Java/PHP/Python开发指南

一、接入前准备（必做）

1. 资质与账号

• 企业资质：营业执照、法人身份证、对公账户、ICP 备案（线上）。
• 开通商户号：拉卡拉商户通 APP / 官网注册，完成实名认证与分账权限签约。
• 获取密钥：商户后台→开发者设置→获取 merchant_id（商户号）、api_key（密钥）、app_id（应用 ID）。

2. 环境与地址

• 基础地址：
  • 沙箱测试：https://sandbox.lakala.com
  • 生产环境：https://api.lakala.com
• 协议：HTTPS，请求 / 响应格式：JSON，字符集：UTF-8。

3. 分账规则配置（后台操作）

• 分账方入网：添加供应商 / 分销商 / 个人（实名 + 银行卡四要素）。
• 规则类型：固定比例 / 固定金额 / 阶梯分账 / 多级分账（≤5 级），单笔最多 20 个分账方。
• 结算模式：T+0 实时分账、T+1~T+90 确权分账，退款自动回滚。

二、公共参数与签名机制

1. 公共请求参数（所有接口必传）

2. 公共响应参数

3. 签名生成步骤（Java/PHP/Python 通用）

1. 参数排序：按 key 字母升序排列（merchant_id→app_id→version→timestamp→req_data）。
2. 拼接字符串：key1=value1&key2=value2&...，req_data 为压缩 JSON（无空格）。
3. RSA 加密：用 api_key 私钥对拼接字符串做SHA256withRSA加密，Base64 编码得 sign。

三、核心 API 接口（含三语言代码示例）

接口 1：支付下单（夹带分账参数）

• 功能：创建订单并指定分账规则，支持微信 / 支付宝 / 云闪付。
• 请求地址：/v3/pay/order/create
• 业务参数（req_data）：

{ "order_id": "平台订单号", "amount": 10000, // 单位：分 "subject": "商品名称", "notify_url": "https://你的域名/notify", // 支付结果回调 "split_flag": 1, // 1=分账，0=不分 "split_type": 1, // 1=比例，2=固定金额 "split_list": [ {"account": "分账方1账号", "ratio": 80}, // 80% {"account": "分账方2账号", "ratio": 20} // 20% ] } 

Java 示例（Spring Boot）

// 1. 配置SDK @Configuration public class LakalaConfig { @Bean public LakalaClient lakalaClient() { return new LakalaClient("merchant_id", "api_key", "app_id"); } } // 2. 下单接口 @Service public class PayService { @Autowired private LakalaClient lakalaClient; public String createOrder(String orderId, int amount) { // 构造请求参数 Map<String, Object> reqData = new HashMap<>(); reqData.put("order_id", orderId); reqData.put("amount", amount); reqData.put("subject", "测试商品"); reqData.put("notify_url", "https://xxx.com/notify"); reqData.put("split_flag", 1); reqData.put("split_type", 1); List<Map<String, Object>> splitList = new ArrayList<>(); splitList.add(Map.of("account", "acc1", "ratio", 80)); splitList.add(Map.of("account", "acc2", "ratio", 20)); reqData.put("split_list", splitList); // 调用接口 try { String response = lakalaClient.post("/v3/pay/order/create", reqData); return response; } catch (Exception e) { e.printStackTrace(); return null; } } } 

• 依赖（pom.xml）：

<dependency> <groupId>cn.lklink</groupId> <artifactId>lakala-pay-sdk-java</artifactId> <version>1.0.0</version> </dependency> 

PHP 示例

<?php // 1. 安装SDK（Composer） // composer require lakala/pay-sdk // 2. 配置与调用 use Lakala\Pay\Client; $config = [ 'merchant_id' => '你的商户号', 'api_key' => '你的密钥', 'app_id' => '你的应用ID', 'sandbox' => true // 沙箱模式 ]; $client = new Client($config); // 构造请求参数 $reqData = [ 'order_id' => 'PHP订单号' . time(), 'amount' => 5000, // 50元 'subject' => 'PHP测试商品', 'notify_url' => 'https://xxx.com/notify.php', 'split_flag' => 1, 'split_type' => 1, 'split_list' => [ ['account' => 'acc1', 'ratio' => 70], ['account' => 'acc2', 'ratio' => 30] ] ]; // 发送请求 try { $response = $client->post('/v3/pay/order/create', $reqData); print_r($response); } catch (Exception $e) { echo $e->getMessage(); } ?> 

Python 示例

# 1. 安装依赖 # pip install requests pycryptodome # 2. 配置与调用 import requests import time from lakala_sign import generate_sign # 自定义签名函数 MERCHANT_ID = "你的商户号" API_KEY = "你的密钥" APP_ID = "你的应用ID" BASE_URL = "https://sandbox.lakala.com" # 构造请求参数 req_data = { "order_id": "PY订单号" + str(int(time.time())), "amount": 8000, # 80元 "subject": "Python测试商品", "notify_url": "https://xxx.com/notify_py", "split_flag": 1, "split_type": 1, "split_list": [ {"account": "acc1", "ratio": 90}, {"account": "acc2", "ratio": 10} ] } # 公共参数 params = { "merchant_id": MERCHANT_ID, "app_id": APP_ID, "version": "3.0", "timestamp": time.strftime("%Y%m%d%H%M%S"), "req_data": str(req_data).replace(" ", ""), "sign": generate_sign(params, API_KEY) } # 发送请求 response = requests.post(f"{BASE_URL}/v3/pay/order/create", json=params) print(response.json()) 

接口 2：分账结果回调（异步接收）

• 功能：支付 / 分账完成后，拉卡拉向 notify_url 推送结果。
• 处理逻辑：
  1. 验证签名（防止伪造）。
  2. 解析参数：order_id、amount、status（SUCCESS/FAIL）、split_result。
  3. 更新订单状态，返回{"code":"0000","msg":"success"}。

Java 回调示例

@RestController @RequestMapping("/notify") public class NotifyController { @PostMapping public String notify(@RequestBody Map<String, Object> params) { // 1. 验证签名 if (!LakalaSignUtil.verify(params, "api_key")) { return "{\"code\":\"9999\",\"msg\":\"sign error\"}"; } // 2. 处理业务 String orderId = (String) params.get("order_id"); String status = (String) params.get("status"); if ("SUCCESS".equals(status)) { // 更新订单为已支付/已分账 } // 3. 返回成功 return "{\"code\":\"0000\",\"msg\":\"success\"}"; } } 

接口 3：分账查询（主动核对）

• 地址：/v3/split/query
• 参数：order_id（平台订单号）
• 返回：分账状态、各分账方金额、完成时间。

接口 4：分账回滚（退款时）

• 地址：/v3/split/rollback
• 参数：order_id、amount（退款金额）
• 说明：退款后自动回滚对应分账，支持 24 小时内撤销、90 天内追回重分。

四、沙箱测试与上线流程

1. 沙箱环境：使用测试商户号与密钥，模拟支付、分账、退款全流程。
2. 联调要点：
   • 回调地址可公网访问（备案域名）。
   • 签名验证通过，参数解析正常。
   • 分账规则生效，资金拆分正确。
3. 上线切换：沙箱测试通过后，将 API 地址改为生产环境，替换正式商户号与密钥。

五、常见问题与避坑

• ❌ 签名错误：检查参数排序、req_data 是否压缩无空格、密钥是否正确。
• ❌ 分账失败：分账方未入网 / 审核未通过、比例总和≠100%、余额不足。
• ❌ 回调接收不到：服务器防火墙拦截、域名未备案、回调地址拼写错误。
• ✅ 建议：先在沙箱完成全流程测试，再上线；关键操作加日志，便于排查。