Java 对接拉卡拉支付完整指南

导入依赖然后根据 SDK 文档拉起支付。

2. 证书准备

需要从拉卡拉官方获取以下证书文件：

• 商户私钥证书（PEM 格式）
• 拉卡拉平台证书（PEM 格式）
• 拉卡拉平台通知证书（PEM 格式）

SDK 初始化配置

1. 配置文件 (application.yml)

在 application.yml 中添加拉卡拉支付配置：

# 拉卡拉支付 SDK 配置
lakala:
  sdk:
    # 拉卡拉应用 ID
    app-id: "OP00000003"
    # 商户证书序列号
    serial-no: "dfba8194c41b84cf"
    # 商户私钥（PEM 格式字符串）
    private-key: |
      -----BEGIN PRIVATE KEY-----
      MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDvDBZyHUDndAGx rIcsCV2njhNO3vCEZotTaWYSYwtDvkcAb1EjsBFabXZaKigpqFXk5XXNI3NIHP9M ...
      -----END PRIVATE KEY-----
    # 拉卡拉平台证书（用于验证 API 响应签名）
    lkl-certificate: |
      -----BEGIN CERTIFICATE-----
      MIIEMTCCAxmgAwIBAgIGAXRTgcMnMA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNVBAYT ...
      -----END CERTIFICATE-----
    # 拉卡拉平台通知证书（用于验证异步通知签名）
    lkl-notify-certificate: |
      -----BEGIN CERTIFICATE-----
      MIIEMTCCAxmgAwIBAgIGAXRTgcMnMA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNVBAYT ...
      -----END CERTIFICATE-----
    # SM4 加密密钥（Base64 编码）
    sm4-key: "LHo55AjrT4aDhAIBZhb5KQ=="
    # API 服务器地址
    server-url: "https://test.wsmsd.cn/sit"
    # 连接超时时间（毫秒）
    connect-timeout: 50000
    # 读取超时时间（毫秒）
    read-timeout: 100000
    # Socket 超时时间（毫秒）
    socket-timeout: 50000

2. SDK 初始化类 (LakalaSdkConfig.java)

创建 SDK 初始化配置类：

package com.shunp.framework.config;

import com.laop.sdk.Config2;
import com.laop.sdk.LKLSDK;
import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;

/**
 * 拉卡拉 SDK 配置类
 */
@Configuration
@Slf4j
public class LakalaSdkConfig {

    @Value("${lakala.sdk.app-id:}")
    private String appId;

    @Value("${lakala.sdk.serial-no:}")
    private String serialNo;

    @Value("${lakala.sdk.private-key:}")
    private String privateKey;

    @Value("${lakala.sdk.lkl-certificate:}")
    private String lklCertificate;

    @Value("${lakala.sdk.lkl-notify-certificate:}")
    private String lklNotifyCertificate;

    @Value("${lakala.sdk.sm4-key:}")
    private String sm4Key;

    @Value("${lakala.sdk.server-url:}")
    private String serverUrl;

    @Value("${lakala.sdk.connect-timeout:50000}")
    private Integer connectTimeout;

    @Value("${lakala.sdk.read-timeout:100000}")
    private Integer readTimeout;

    @Value("${lakala.sdk.socket-timeout:50000}")
    private Integer socketTimeout;

    /**
     * 初始化 LKLSDK
     */
    @PostConstruct
    public void initLklSdk() {
        try {
            log.info("开始初始化拉卡拉 SDK...");
            // 校验必要参数
            if (appId == null || appId.trim().isEmpty()) {
                log.warn("拉卡拉 SDK appId 未配置，跳过初始化");
                return;
            }
            // ... 其他参数校验
            // 创建 Config2 对象
            Config2 config = new Config2();
            config.setAppId(appId.trim());
            config.setSerialNo(serialNo.trim());
            config.setPriKey(privateKey.trim());
            config.setLklCer(lklCertificate.trim());
            config.setLklNotifyCer(lklNotifyCertificate.trim());
            config.setServerUrl(serverUrl.trim());
            // 可选参数
            if (sm4Key != null && !sm4Key.trim().isEmpty()) {
                config.setSm4Key(sm4Key.trim());
            }
            if (connectTimeout != null) {
                config.setConnectTimeout(connectTimeout);
            }
            if (readTimeout != null) {
                config.setReadTimeout(readTimeout);
            }
            if (socketTimeout != null) {
                config.setSocketTimeout(socketTimeout);
            }
            // 初始化 SDK
            boolean initResult = LKLSDK.init(config);
            if (initResult) {
                log.info("拉卡拉 SDK 初始化成功，appId: {}", appId);
            } else {
                log.error("拉卡拉 SDK 初始化失败，appId: {}", appId);
            }
        } catch (Exception e) {
            log.error("拉卡拉 SDK 初始化异常", e);
        }
    }
}

支付接口实现

1. 支付 Controller (LakalaPayController.java)

package com.shunp.web.controller.pay;

import com.alibaba.fastjson2.JSONObject;
import com.laop.sdk.LKLSDK;
import com.laop.sdk.exception.SDKException;
import com.laop.sdk.request.V3CcssCounterOrderSpecialCreateEncryRequest;
import com.shunp.common.core.controller.BaseController;
import com.shunp.common.core.domain.AjaxResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import java.text.SimpleDateFormat;
import java.util.Calendar;

/**
 * 拉卡拉支付 Controller
 */
@RestController
@RequestMapping("/opmanager/pay/lakala")
@Slf4j
@Tag(name = "拉卡拉支付")
public class LakalaPayController extends BaseController {

    private final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyyMMddHHmmss");

    /**
     * 收银台订单创建（全报文加密）
     */
    @PostMapping("/counter/order/create/encry")
    @Operation(summary = "收银台订单创建（全报文加密）")
    public AjaxResult createCounterOrderEncry(@RequestBody CounterOrderCreateRequest request) {
        try {
            // 如果前端传入了订单号，使用前端的；否则生成新的
            String orderNo = request.getOutOrderNo() != null && !request.getOutOrderNo().trim().isEmpty()
                    ? request.getOutOrderNo()
                    : generateOrderNo();
            log.info("开始创建收银台订单（全报文加密），订单号：{}，商户号：{}，交易设备 ID：{}", orderNo, request.getMerchantNo(), request.getVposId());

            // 构建请求对象
            V3CcssCounterOrderSpecialCreateEncryRequest lakalaRequest = new V3CcssCounterOrderSpecialCreateEncryRequest();
            lakalaRequest.setOutOrderNo(orderNo);
            lakalaRequest.setMerchantNo(request.getMerchantNo());
            lakalaRequest.setVposId(request.getVposId());
            lakalaRequest.setChannelId(request.getChannelId());
            lakalaRequest.setTotalAmount(request.getTotalAmount());

            // 设置订单有效期
            if (request.getOrderEfficientTime() != null) {
                lakalaRequest.setOrderEfficientTime(request.getOrderEfficientTime());
            } else {
                // 默认 7 天有效期
                Calendar calendar = Calendar.getInstance();
                calendar.add(Calendar.DAY_OF_MONTH, 7);
                lakalaRequest.setOrderEfficientTime(dateFormat.format(calendar.getTime()));
            }

            // 设置回调地址
            lakalaRequest.setNotifyUrl(request.getNotifyUrl());
            lakalaRequest.setOrderInfo(request.getOrderInfo());

            // 调用 LKLSDK 创建订单
            String response = LKLSDK.httpPost(lakalaRequest, true, true);
            log.info("收银台订单创建完成，响应：{}", response);
            return AjaxResult.success("订单创建成功", response);
        } catch (SDKException e) {
            log.error("收银台订单创建失败，SDK 异常：{}", e.getMessage(), e);
            return AjaxResult.error("订单创建失败：" + e.getMessage());
        } catch (Exception e) {
            log.error("收银台订单创建失败，系统异常：{}", e.getMessage(), e);
            return AjaxResult.error("订单创建失败：" + e.getMessage());
        }
    }

    /**
     * 拉卡拉支付回调通知
     */
    @PostMapping("/notify")
    @Operation(summary = "拉卡拉支付回调通知")
    public String paymentNotify(HttpServletRequest request) {
        try {
            log.info("收到拉卡拉支付回调通知");
            // 验证回调签名
            String notifyBody = LKLSDK.notificationHandle(request);
            log.info("回调签名验证成功，通知内容：{}", notifyBody);

            // 解析回调数据
            PaymentNotifyData notifyData = JSONObject.parseObject(notifyBody, PaymentNotifyData.class);
            log.info("支付回调信息 - 商户订单号：{}，支付订单号：{}，支付状态：{}，支付金额：{}，支付时间：{}", 
                    notifyData.getOutOrderNo(), notifyData.getPayOrderNo(), notifyData.getPayStatus(), 
                    notifyData.getPayAmount(), notifyData.getPayTime());

            // 根据业务需求处理回调逻辑（需加订单级锁）
            if ("SUCCESS".equals(notifyData.getPayStatus())) {
                // 支付成功处理
                log.info("支付成功，订单号：{}，金额：{}", notifyData.getOutOrderNo(), notifyData.getPayAmount());
                // 这里可以调用业务服务更新订单状态
                // orderService.updateOrderStatus(notifyData.getOutOrderNo(), "PAID");
            } else if ("FAILED".equals(notifyData.getPayStatus())) {
                // 支付失败处理
                log.warn("支付失败，订单号：{}", notifyData.getOutOrderNo());
            } else {
                log.warn("未知支付状态：{}，订单号：{}", notifyData.getPayStatus(), notifyData.getOutOrderNo());
            }

            // 返回成功响应给拉卡拉服务器
            return "success";
        } catch (SDKException e) {
            log.error("回调签名验证失败：{}", e.getMessage(), e);
            return "fail";
        } catch (Exception e) {
            log.error("处理支付回调异常：{}", e.getMessage(), e);
            return "fail";
        }
    }

    /**
     * 生成订单号
     */
    private String generateOrderNo() {
        return "LKL" + System.currentTimeMillis() + (int) (Math.random() * 1000);
    }

    /**
     * 收银台订单创建请求 DTO
     */
    @Data
    public static class CounterOrderCreateRequest {
        private String outOrderNo;       // 商户订单号
        private String merchantNo;       // 银联商户号
        private String vposId;           // 交易设备标识
        private String channelId;        // 渠道号
        private Long totalAmount;        // 订单金额（单位：分）
        private String orderEfficientTime; // 订单有效期
        private String notifyUrl;        // 回调地址
        private String orderInfo;        // 订单标题
        private Integer supportCancel;   // 是否支持撤销
        private Integer supportRefund;   // 是否支持退款
        private Integer supportRepeatPay;// 是否支持多次支付
        private String callbackUrl;      // 前端跳转地址
        private String counterParam;     // 收银台参数
        private String counterRemark;    // 收银台备注
    }

    /**
     * 拉卡拉支付回调数据 DTO
     */
    @Data
    public static class PaymentNotifyData {
        private String outOrderNo;       // 商户订单号
        private String payOrderNo;       // 拉卡拉支付订单号
        private String payStatus;        // 支付状态 SUCCESS-成功 FAILED-失败
        private String payAmount;        // 支付金额（单位：分）
        private String payTime;          // 支付完成时间 yyyyMMddHHmmss
        private String merchantNo;       // 商户号
        private String vposId;           // 交易设备标识
        private String payChannel;       // 支付渠道
        private String payMethod;        // 支付方式
        private String attach;           // 附加数据
    }
}

回调处理

回调地址配置

在创建订单时，需要设置回调地址：

// 设置回调地址
lakalaRequest.setNotifyUrl("http://your-domain/opmanager/pay/lakala/notify");

回调数据格式

拉卡拉回调发送的 JSON 数据格式：

{
  "out_order_no": "LKL1703123456789",
  "pay_order_no": "26011611012001101011002063626",
  "pay_status": "SUCCESS",
  "pay_amount": "1",
  "pay_time": "20260116145443",
  "merchant_no": "8222900701106PZ",
  "vpos_id": "2021052614391",
  "pay_channel": "ALIPAY",
  "pay_method": "SCAN",
  "attach": "附加数据"
}

回调处理逻辑

1. 签名验证：使用 LKLSDK.notificationHandle() 验证回调签名
2. 数据解析：将 JSON 字符串解析为 PaymentNotifyData 对象
3. 业务处理：
   • 支付成功：更新订单状态为已支付
   • 支付失败：记录失败原因
   • 其他状态：记录日志并告警
4. 响应处理：返回 "success" 告知拉卡拉处理成功

完整代码示例

1. 前端调用示例

// 创建支付订单
const createOrder = async (orderData) => {
    const response = await fetch('/opmanager/pay/lakala/counter/order/create/encry', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            merchantNo: '8222900701106PZ',
            vposId: '2021052614391',
            channelId: '2021052614391',
            totalAmount: 100, // 1 元 = 100 分
            notifyUrl: 'http://your-domain/opmanager/pay/lakala/notify',
            orderInfo: '商品购买'
        })
    });
    const result = await response.json();
    if (result.code === 200) {
        // 获取支付链接并跳转
        const payUrl = result.data.counter_url;
        window.location.href = payUrl;
    }
};

2. 回调处理业务逻辑示例

@Service
public class OrderService {

    @Autowired
    private OrderMapper orderMapper;

    /**
     * 更新订单支付状态
     */
    @Transactional
    public void updateOrderStatus(String orderNo, String status) {
        // 加订单级锁防止并发问题
        Order order = orderMapper.selectByOrderNoForUpdate(orderNo);
        if (order != null && "PENDING".equals(order.getStatus())) {
            order.setStatus(status);
            order.setPayTime(new Date());
            orderMapper.updateById(order);
            // 发送支付成功通知
            sendPaymentSuccessNotification(order);
        }
    }
}

注意事项

1. 安全配置

• 私钥证书妥善保管，不要在日志中输出
• 使用 HTTPS 协议传输敏感数据
• 定期更新证书，避免过期

2. 订单处理

• 实现幂等性，避免重复处理同一订单
• 添加订单级锁，防止并发更新问题
• 记录详细的支付流水日志

3. 异常处理

• 妥善处理网络异常和超时
• 实现重试机制，但避免无限重试
• 监控支付成功率和异常情况

4. 回调处理

• 回调接口必须返回 "success"，否则拉卡拉会重试
• 回调处理要快速响应，避免超时
• 验证回调数据的完整性和正确性

常见问题

Q1: SDK 初始化失败怎么处理？

A: 检查配置文件中的证书格式是否正确，私钥是否匹配，网络连接是否正常。

Q2: 订单创建失败的原因？

A: 可能是参数格式错误、金额超出限制、商户状态异常等。检查返回的错误信息。

Q3: 回调没有收到怎么办？

A: 检查回调地址是否正确可访问，防火墙是否阻止了请求，服务器是否正常运行。

Q4: 如何处理重复回调？

A: 在业务逻辑中检查订单状态，只有在特定状态下才处理回调，避免重复处理。

Q5: 支付状态不一致怎么办？

A: 以拉卡拉回调为准，主动查询订单状态进行校对，记录异常情况并告警。

本文档提供完整的拉卡拉支付集成方案，如有问题请参考官方文档或联系技术支持。