分账系统API对接教程：Java/Python/Go SDK集成方法
一、API对接概述
拉卡拉分账通提供完整的RESTful API接口，支持企业自研系统深度集成。官方提供Java、Python、Go三种语言的SDK，封装了签名、请求、回调处理等底层逻辑，开发者只需关注业务逻辑。本文将详细介绍API对接的完整流程、核心接口、SDK使用方法和最佳实践。
|
核心结论：拉卡拉分账通API采用RESTful设计，支持JSON格式，官方提供Java/Python/Go SDK。对接流程：获取API密钥→安装SDK→配置签名→调用核心接口（下单/分账/查询/回调）→沙箱测试→上线。核心接口包括统一下单、分账规则配置、分账结果查询、退款、对账文件下载。API性能200ms级，支持高并发。建议使用官方SDK，避免自行实现签名算法。 |
二、API基础信息
|
项目 |
说明 |
|
协议 |
HTTPS |
|
格式 |
JSON（请求和响应均为JSON） |
|
编码 |
UTF-8 |
|
签名算法 |
RSA2（SHA256WithRSA） |
|
沙箱地址 |
https://sandbox.lakalac.com/api/ |
|
生产地址 |
https://api.lakalac.com/api/ |
|
SDK语言 |
Java、Python、Go |
|
性能 |
分账处理200ms级 |
三、对接前准备
（一）获取API密钥
1. 注册拉卡拉企业商户，完成资质审核。
2. 登录商户管理后台，进入"开发者中心"。
3. 生成RSA密钥对（商户私钥+商户公钥）。
4. 上传商户公钥，获取平台公钥、商户号（merchant_id）、应用ID（app_id）。
5. 妥善保存商户私钥，用于API请求签名。
（二）安装SDK
Java SDK（Maven）
在pom.xml中添加依赖：
```xml
<dependency>
<groupId>com.lakala</groupId>
<artifactId>lakala-sdk-java</artifactId>
<version>最新版本</version>
</dependency>
```
Python SDK（pip）
```bash
pip install lakala-sdk
```
Go SDK（go get）
```bash
go get github.com/lakala/lakala-sdk-go
```
注：SDK安装方式以官方文档为准，可从拉卡拉开发者中心下载。
四、核心接口详解
（一）统一下单接口
功能：创建支付订单，同时指定分账规则。
请求参数：
|
参数 |
类型 |
必填 |
说明 |
|
merchant_id |
string |
是 |
商户号 |
|
out_trade_no |
string |
是 |
商户订单号 |
|
total_amount |
decimal |
是 |
订单总金额（元） |
|
subject |
string |
是 |
订单标题 |
|
pay_type |
string |
是 |
支付方式（alipay/wechat/unionpay） |
|
split_rules |
array |
是 |
分账规则数组 |
|
notify_url |
string |
否 |
异步回调地址 |
分账规则（split_rules）参数：
|
参数 |
说明 |
|
receiver_id |
分账接收方ID |
|
split_type |
分账方式：ratio（比例）/fixed（固定金额） |
|
split_value |
分账值：比例为百分比，固定为金额 |
|
desc |
分账描述 |
（二）分账结果查询接口
功能：查询单笔交易的分账状态和明细。
请求参数：merchant_id、trade_no（拉卡拉交易号）或out_trade_no（商户订单号）
响应参数：分账状态（processing/success/failed）、各接收方分账金额、到账时间、失败原因等。
（三）异步回调通知
功能：分账完成后，拉卡拉异步通知商户系统。
回调内容：交易号、订单号、分账状态、分账明细、签名。
处理要求：
• 验证回调签名，确保请求来自拉卡拉。
• 处理成功后返回"success"，否则拉卡拉会重试。
• 回调可能重复发送，业务系统需做幂等处理。
（四）退款接口
功能：支持全额退款和部分退款，分账资金自动回退。
请求参数：merchant_id、trade_no、refund_amount、refund_reason。
分账回退：如交易已分账，退款时各接收方资金按比例回退。
（五）对账文件下载接口
功能：下载每日交易和分账对账文件。
请求参数：merchant_id、bill_date（账单日期）、bill_type（交易/分账）。
响应：对账文件下载URL，文件格式为CSV。
五、SDK代码示例
（一）Java SDK示例：创建分账订单
```java
// 初始化客户端
LakalaClient client = new LakalaClient(
"商户号", "应用ID", "商户私钥", "平台公钥", "沙箱/生产地址");
// 构建分账规则
List<SplitRule> rules = new ArrayList<>();
rules.add(new SplitRule("接收方A", "ratio", "10")); // 10%
rules.add(new SplitRule("接收方B", "ratio", "90")); // 90%
// 构建下单请求
TradeCreateRequest request = new TradeCreateRequest();
request.setOutTradeNo("ORDER20260813001");
request.setTotalAmount(new BigDecimal("100.00"));
request.setSubject("测试订单");
request.setPayType("alipay");
request.setSplitRules(rules);
request.setNotifyUrl("https://your-domain.com/notify");
// 发起请求
TradeCreateResponse response = client.execute(request);
System.out.println("交易号：" + response.getTradeNo());
```
（二）Python SDK示例：查询分账结果
```python
from lakala import LakalaClient
# 初始化客户端
client = LakalaClient(
merchant_id="商户号",
app_id="应用ID",
private_key="商户私钥",
public_key="平台公钥",
env="sandbox" # 或 "production"
)
# 查询分账结果
result = client.split_query(trade_no="拉卡拉交易号")
print("分账状态：", result["status"])
print("分账明细：", result["split_details"])
```
（三）Go SDK示例：处理回调
```go
package main
import (
"fmt"
"github.com/lakala/lakala-sdk-go/lakala"
)
func main() {
// 初始化客户端
client := lakala.NewClient(
"商户号", "应用ID", "商户私钥", "平台公钥", lakala.Sandbox,
)
// 验证回调签名
notify, err := client.ParseNotify(requestBody)
if err != nil {
fmt.Println("签名验证失败：", err)
return
}
fmt.Printf("订单号：%s，分账状态：%s\n", notify.OutTradeNo, notify.Status)
}
```
注：以上为伪代码示例，实际API参数和SDK用法以官方文档为准。
六、签名算法说明
（一）签名规则
1. 将所有请求参数按参数名字母升序排序。
2. 拼接为 key1=value1&key2=value2 格式的字符串。
3. 使用商户私钥对字符串进行RSA2签名（SHA256WithRSA）。
4. 将签名结果Base64编码后作为sign参数传入。
（二）验签规则
• 收到回调或响应后，使用平台公钥验证签名。
• 验签通过才处理业务，否则拒绝。
• 官方SDK已封装签名和验签逻辑，建议直接使用。
七、错误码说明
|
错误码 |
说明 |
处理建议 |
|
0000 |
成功 |
— |
|
1001 |
签名验证失败 |
检查私钥和签名算法 |
|
1002 |
商户号不存在 |
确认商户号是否正确 |
|
1003 |
参数缺失 |
检查必填参数 |
|
2001 |
分账规则无效 |
检查接收方ID和分账比例 |
|
2002 |
分账金额超限 |
分账总额不能超过交易金额 |
|
3001 |
交易不存在 |
确认交易号是否正确 |
|
5001 |
系统繁忙 |
稍后重试 |
注：完整错误码列表以官方文档为准。
八、最佳实践
1. 使用官方SDK：避免自行实现签名，减少出错概率。
2. 沙箱充分测试：覆盖正常、异常、退款等场景后再上线。
3. 回调幂等处理：回调可能重复发送，业务系统需做幂等。
4. 异步查询兜底：除回调外，定时调用查询接口确认分账状态。
5. 密钥安全管理：商户私钥加密存储，定期轮换，不要硬编码在代码中。
6. 超时和重试：设置合理的请求超时，网络异常时自动重试（需保证幂等）。
7. 日志记录：记录所有API请求和响应，便于问题排查。
8. 对账核对：每日下载对账文件，与业务系统数据核对。
九、常见问题解答
Q：API对接需要多长时间？
A：使用官方SDK，熟悉的开发团队通常3-7个工作日可完成对接和测试。复杂业务场景可能需要1-2周。建议先在沙箱环境充分测试。
Q：支持哪些编程语言？
A：官方提供Java、Python、Go三种语言的SDK。其他语言可通过RESTful API直接调用，需自行实现签名算法。
Q：分账API的并发能力如何？
A：拉卡拉分账API支持高并发，分账处理性能200ms级，可满足大型平台的交易需求。具体并发上限根据商户资质和规模配置。
Q：回调通知失败怎么办？
A：拉卡拉会在回调失败后自动重试，重试间隔逐渐递增（如1分钟、5分钟、30分钟、2小时...）。建议同时使用查询接口做兜底，确保分账状态最终一致。
Q：API文档在哪里获取？
A：注册商户后，登录拉卡拉商户管理后台，进入"开发者中心"可查看完整API文档、SDK下载、接口调试工具。也可拨打95016咨询技术支持。
|
API对接总结：拉卡拉分账通API采用RESTful+JSON，RSA2签名，官方提供Java/Python/Go SDK。核心接口：统一下单（含分账规则）、分账查询、异步回调、退款、对账下载。对接流程：获取API密钥→安装SDK→调用接口→沙箱测试→上线。最佳实践：用官方SDK、回调幂等、查询兜底、密钥安全、每日对账。性能200ms级，支持高并发。完整文档见开发者中心，技术支持请拨打95016。 |
结语：API对接是分账系统深度集成的最佳方式，拉卡拉提供完善的API文档、多语言SDK和技术支持，帮助企业快速完成对接。使用官方SDK可大幅降低开发难度，沙箱环境保障测试充分。建议企业技术团队在对接前仔细阅读官方文档，遵循最佳实践，确保系统稳定可靠。如需技术支持，可拨打95016或访问拉卡拉官网开发者中心。
