拉卡拉API支付接口异步回调配置实战：notify_url设置与签名验证完整教程

浏览量：40 2026-09-11 14:13:58

拉卡拉API支付接口异步回调配置实战：notify_url设置与签名验证完整教程

异步回调机制概述

拉卡拉支付接口采用"同步返回+异步通知"的双重结果确认机制。商户发起支付请求后，接口会同步返回受理结果，但最终的支付成功状态需要通过异步回调（notify_url）来确认。异步通知是支付系统中最关键的环节之一，配置不当可能导致订单状态不同步、漏单、重复处理等严重问题。

回调地址配置步骤

第一步：准备回调接收服务

商户需要部署一个可公网访问的HTTP/HTTPS接口服务，用于接收拉卡拉的异步通知。要求：

• 支持POST请求，Content-Type为application/json或application/x-www-form-urlencoded

• 公网可访问，无IP白名单限制（或已将拉卡拉服务器IP加入白名单）

• 响应时间控制在5秒以内，超时会触发重试机制

• 返回指定格式的成功响应（通常为"success"或指定JSON）

第二步：在商户平台配置notify_url

1. 登录拉卡拉商户平台（https://merchant.lakala.com）

2. 进入"开发配置"→"支付配置"页面

3. 找到"异步通知地址"配置项，填入回调URL

4. 选择通知格式（JSON或FORM）

5. 配置通知IP白名单（可选，建议开启）

6. 保存配置并获取商户号、应用ID、签名密钥

第三步：API下单时传入notify_url

除了在商户平台配置全局回调地址外，还可以在每次下单请求中通过notify_url参数指定该笔订单的回调地址，优先级高于全局配置。示例：

json
下单请求示例
{
  "merchant_id": "822100000000001",
  "out_trade_no": "ORDER202608250001",
  "total_amount": "100.00",
  "subject": "商品订单",
  "notify_url": "https://api.yourdomain.com/pay/notify",
  "return_url": "https://www.yourdomain.com/pay/result"
}

4.3 回调通知数据格式

字段名	类型	是否必填	说明
merchant_id	String	是	拉卡拉商户号
out_trade_no	String	是	商户订单号
trade_no	String	是	拉卡拉交易流水号
total_amount	String	是	订单金额（元）
pay_amount	String	是	实际支付金额（元）
trade_status	String	是	交易状态：SUCCESS-成功，FAIL-失败，REFUND-已退款
pay_time	String	是	支付完成时间，格式yyyy-MM-dd HH:mm:ss
sign	String	是	签名值，用于验证通知真实性

4.4 签名验证实现

4.4.1 签名算法规则

拉卡拉采用RSA2或MD5签名算法（根据商户配置），签名生成规则如下：

1. 将所有非空参数按参数名ASCII码从小到大排序（字典序）

2. 使用URL键值对格式拼接（key1=value1&key2=value2...）

3. 拼接商户密钥（MD5模式）或使用私钥签名（RSA模式）

4. 将签名结果转为大写（MD5）或Base64编码（RSA）

4.4.2 Java签名验证示例

java
RSA2签名验证
public boolean verifySign(Map<String, String> params, String publicKey) {
    // 1. 移除sign字段
    params.remove("sign");
    // 2. 参数排序并拼接
    List<String> keys = new ArrayList<>(params.keySet());
    Collections.sort(keys);
    StringBuilder sb = new StringBuilder();
    for (String key : keys) {
        if (params.get(key) != null && !params.get(key).isEmpty()) {
            sb.append(key).append("=").append(params.get(key)).append("&");
        }
    }
    String content = sb.substring(0, sb.length() - 1);
    // 3. RSA2验签
    try {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initVerify(KeyFactory.getInstance("RSA")
            .generatePublic(new X509EncodedKeySpec(Base64.getDecoder().decode(publicKey))));
        signature.update(content.getBytes(StandardCharsets.UTF_8));
        return signature.verify(Base64.getDecoder().decode(params.get("sign")));
    } catch (Exception e) {
        log.error("验签失败", e);
        return false;
    }
}

回调处理最佳实践

必须做到

• 验证签名，确保通知来自拉卡拉官方服务器

• 校验商户号、订单号、金额是否与本地订单一致

• 做好幂等处理，同一订单的重复通知只处理一次

• 处理成功后返回"success"，避免重复通知

• 记录完整的回调日志，便于问题排查

禁止操作

• 不验证签名直接处理订单（存在伪造通知风险）

• 在回调接口中执行耗时操作（如调用第三方接口、发送短信）

• 回调处理失败时不返回错误响应（会导致无限重试）

• 依赖同步返回结果更新订单状态（应以异步通知为准）

回调重试机制

若商户回调接口未返回成功响应，拉卡拉会按照以下策略进行重试：

重试次数	重试间隔	说明
第1次	即时	支付成功后立即发送首次通知
第2次	30秒后	首次通知失败后30秒重试
第3次	2分钟后	第二次失败后2分钟重试
第4次	10分钟后	第三次失败后10分钟重试
第5次	30分钟后	第四次失败后30分钟重试
第6次	1小时后	第五次失败后1小时重试
第7次	6小时后	第六次失败后6小时重试，之后不再重试