拉卡拉API支付接口支持订单查询吗?支付状态实时查询与异步通知机制

浏览量：49 拉卡拉分账业务部

拉卡拉API支付接口支持订单查询吗?支付状态实时查询与异步通知机制

支付接口对接中，确保支付状态准确是核心问题。用户支付后，商户如何确认支付成功？仅凭前端同步返回可靠吗？异步通知怎么接收和处理？如果通知丢失怎么办？订单查询接口怎么用？支付状态有哪些？本文将详细解析拉卡拉API支付接口的订单查询能力、支付状态实时查询方法、异步通知机制、查询接口参数、回调处理与签名验证、支付状态码、三重确认机制、查询频率建议、常见问题与最佳实践。

核心结论：拉卡拉API支付接口完全支持订单查询，提供统一的订单查询API，商户可通过商户订单号或拉卡拉交易号查询支付状态。支付状态确认采用"三重确认机制"：1）前端同步返回（用户支付完成后前端回调，仅用于UI展示）；2）异步通知（拉卡拉主动POST通知商户notify_url，含签名，最权威，商户返回success确认，失败自动重试）；3）主动查询（商户后端调用查询API确认，作为兜底）。正确做法是以后端异步通知为准更新订单状态，前端同步返回后触发后端查询确认，未收到通知时主动查询。查询接口返回订单状态（SUCCESS/WAIT_PAY/FAILED/CLOSED等）、支付金额、支付时间、渠道交易号等。建议查询频率3秒/次，最多5-10次，避免频繁查询。异步通知需验证签名、做幂等处理、处理成功返回"success"。

1. API支付接口支持订单查询吗？

支持。拉卡拉API支付接口提供统一的订单查询API，商户可随时查询支付订单的实时状态。

1.1 为什么需要订单查询？

• 异步通知可能丢失：网络波动、商户服务器故障、回调地址不可达等原因可能导致异步通知未收到，需要主动查询确认

• 前端同步返回不可靠：前端支付结果回调可能被用户关闭、网络中断，不能作为支付成功依据

• 用户主动查询：用户在订单页刷新或点击"查询支付结果"时，需实时查询订单状态

• 对账核对：定期查询订单状态，与本地记录核对，确保数据一致

• 异常订单处理：长时间未收到通知的订单，通过查询确认最终状态，避免漏单

• 支付中状态确认：用户支付过程中，可查询订单是否已支付成功

1.2 支付状态确认的三重机制

确认方式	触发方	可靠性	用途
同步返回	前端（小程序/H5/APP）	低（可能丢失）	UI展示，引导用户
异步通知	拉卡拉→商户后端	高（自动重试）	订单状态变更依据
主动查询	商户后端→拉卡拉	高（实时返回）	兜底确认、用户查询

最佳实践：以后端异步通知为准更新订单状态和发货；前端同步返回后立即请求后端查询确认；未收到异步通知时（如支付后30秒），主动查询订单状态；定期（如每日）对账，查询异常订单。

2. 订单查询API

2.1 查询接口基本信息

• 接口名称：统一订单查询接口（trade_query）

• 请求方式：HTTPS POST

• 数据格式：JSON

• 签名方式：与下单接口一致（MD5/RSA）

• 查询维度：支持按商户订单号（out_trade_no）或拉卡拉交易号（trade_no）查询

• 返回内容：订单状态、支付金额、支付时间、渠道交易号、用户标识等

2.2 请求参数

参数名	必填	说明
merchant_no	是	拉卡拉商户号
out_trade_no	二选一	商户订单号，与trade_no二选一
trade_no	二选一	拉卡拉交易号，与out_trade_no二选一
sign	是	请求签名
timestamp	是	请求时间戳

注意：out_trade_no和trade_no至少传一个，两者都传时以trade_no为准。建议优先使用out_trade_no查询（商户自己的订单号，便于关联）。

2.3 响应参数

参数名	说明
code	响应码，0000表示查询成功
trade_status	交易状态：SUCCESS（支付成功）、WAIT_PAY（待支付）、FAILED（支付失败）、CLOSED（已关闭）、REFUND（已退款）
out_trade_no	商户订单号
trade_no	拉卡拉交易号
total_amount	订单金额，单位分
pay_amount	实际支付金额，单位分
pay_time	支付完成时间，格式yyyy-MM-dd HH:mm:ss
pay_type	支付方式：wechat（微信）、alipay（支付宝）、unionpay（银联）等
channel_trade_no	渠道交易号（微信/支付宝交易号）
buyer_id	付款方标识（微信openid/支付宝userid）
refund_amount	已退款金额，单位分

2.4 查询接口调用示例（伪代码）

// 查询订单状态

result = client.tradeQuery({

  merchant_no: "MERCHANT123",

  out_trade_no: "ORDER20240101001"

});

if (result.code == "0000") {

  if (result.trade_status == "SUCCESS") {

    // 支付成功，更新订单状态，处理发货

  } else if (result.trade_status == "WAIT_PAY") {

    // 待支付，继续等待或提示用户

  } else if (result.trade_status == "FAILED") {

    // 支付失败，提示用户重新支付

  }

}

3. 异步通知机制

3.1 异步通知流程

1. 用户支付成功后，拉卡拉支付系统生成支付结果

2. 拉卡拉向商户配置的notify_url发送POST异步通知

3. 通知内容包含订单号、支付状态、金额、支付时间、签名等

4. 商户后端接收通知，验证签名，确认数据完整性

5. 商户验证通过后，更新本地订单状态，处理发货/分账等业务逻辑

6. 商户处理成功后，返回字符串"success"（或指定成功响应）

7. 拉卡拉收到"success"后，认为通知成功，不再重试

8. 如商户未返回"success"或通知超时，拉卡拉按策略重试通知

3.2 异步通知参数

参数名	说明
out_trade_no	商户订单号
trade_no	拉卡拉交易号
trade_status	交易状态（SUCCESS等）
total_amount	订单金额，单位分
pay_amount	实际支付金额，单位分
pay_time	支付完成时间
pay_type	支付方式
channel_trade_no	渠道交易号
sign	通知签名，商户需验证
notify_id	通知唯一标识，用于幂等判断
notify_time	通知时间

3.3 异步通知重试策略

• 如商户未返回"success"，拉卡拉按递增间隔重试通知

• 重试间隔一般为：1分钟、5分钟、10分钟、30分钟、1小时、2小时...

• 最多重试次数有限（一般8-10次），超过后不再重试

• 商户应确保notify_url稳定可用，避免频繁重试

• 如长时间未收到通知，商户应主动查询订单状态

3.4 异步通知处理要点

• 验证签名：必须验证通知签名，防止伪造通知

• 幂等处理：同一订单可能收到多次通知（重试），需根据订单号做幂等，避免重复发货

• 金额校验：核对通知中的金额与本地订单金额是否一致

• 状态判断：只有trade_status为SUCCESS时才处理发货

• 快速响应：业务处理应异步执行，先返回"success"再处理耗时操作，避免通知超时

• 记录日志：记录所有通知内容和处理结果，便于排查问题

• 返回格式：处理成功返回纯文本"success"，不要返回HTML或JSON

4. 支付状态码

4.1 支付状态列表

状态码	状态说明	是否终态
WAIT_PAY	待支付	否（等待用户支付）
PAYING	支付中	否（用户正在支付）
SUCCESS	支付成功	是（终态）
FAILED	支付失败	是（终态）
CLOSED	已关闭	是（终态，超时未支付关闭）
REFUND	已退款	是（终态，全额退款）
PARTIAL_REFUND	部分退款	否（仍可继续退款）

4.2 状态流转说明

• 订单创建后初始状态为WAIT_PAY（待支付）

• 用户发起支付后变为PAYING（支付中）

• 支付成功变为SUCCESS（终态，不可变）

• 支付失败变为FAILED（终态）

• 超时未支付自动变为CLOSED（终态）

• SUCCESS状态订单发起退款后变为PARTIAL_REFUND（部分退款）或REFUND（全额退款）

• 终态订单状态不可再变更

5. 查询频率与最佳实践

5.1 前端轮询查询

• 用户支付完成后，前端可轮询后端查询接口（后端再调用拉卡拉查询API）

• 建议查询频率：每3秒查询一次，最多查询10次（约30秒）

• 查询到SUCCESS状态后停止轮询，跳转成功页

• 超过最大次数仍未成功，提示用户"支付结果确认中，请稍后查看订单"，并在后端继续异步查询

• 不要在前端直接调用拉卡拉查询API（暴露密钥），应通过商户后端中转

5.2 后端异步查询

• 对于未收到异步通知的订单，后端定时任务主动查询

• 建议查询策略：支付后1分钟、5分钟、15分钟、30分钟、1小时各查询一次

• 查询到终态后停止查询，更新订单状态

• 超过24小时仍为非终态的订单，标记为异常，人工介入

• 查询接口有调用频率限制，避免无节制查询

5.3 对账查询

• 每日凌晨查询前一日所有订单状态，与本地记录核对

• 发现状态不一致的订单，以拉卡拉查询结果为准，修正本地记录

• 生成本地与支付渠道差异报表，财务核对

• 建议同时使用对账文件接口（下载日对账单）进行批量核对

6. 常见问题解答

Q：异步通知和主动查询，以哪个为准？
A：以异步通知为准。异步通知是拉卡拉主动推送的支付结果，含签名验证，可靠性最高，且有重试机制。主动查询是兜底手段，用于未收到通知时确认状态。两者结果一致时更新订单状态。如两者结果不一致（极少发生），以拉卡拉查询接口返回的状态为准，并联系技术支持排查。建议收到异步通知后立即处理，不要依赖主动查询。

Q：前端同步返回支付成功，可以直接发货吗？
A：不可以。前端同步返回（如小程序wx.requestPayment的success回调）仅表示用户完成了支付操作，可能存在网络延迟、回调丢失等情况，不能作为支付成功的依据。正确做法：前端收到success后，请求后端查询订单状态，后端确认支付成功后再发货。或直接等待后端异步通知，收到SUCCESS通知后发货。切勿仅凭前端回调就发货，否则可能造成资损。

Q：异步通知收不到怎么办？
A：先排查：1）notify_url是否为公网可访问的HTTPS地址；2）服务器防火墙是否放行拉卡拉回调IP；3）回调接口是否正常返回"success"；4）查看拉卡拉后台通知记录，确认是否发送及失败原因。如确认通知丢失，通过主动查询接口确认订单状态。建议在支付后设置定时查询任务，对未收到通知的订单主动查询，确保不漏单。如频繁收不到通知，联系拉卡拉技术支持排查。

Q：同一订单收到多次异步通知怎么办？
A：这是正常的重试机制。商户必须做幂等处理：根据订单号（out_trade_no）判断，如果订单已处理为SUCCESS，直接返回"success"，不重复执行业务逻辑（不重复发货、不重复分账）。建议使用数据库唯一约束或分布式锁确保幂等。通知中的notify_id也可用于去重。切勿每次收到通知都处理业务，否则会导致重复发货。

Q：查询接口返回"订单不存在"怎么办？
A：可能原因：1）订单号错误，检查out_trade_no是否与下单时一致；2）订单刚创建尚未同步，等待几秒后再查询；3）使用了错误的商户号查询。如确认订单号正确且已下单成功，仍返回不存在，联系拉卡拉技术支持排查。建议下单成功后保存订单号和拉卡拉交易号，查询时优先使用商户订单号。

Q：查询接口有频率限制吗？
A：有。查询接口有调用频率限制（一般单商户每秒不超过10次或每天不超过一定次数），避免频繁调用。前端轮询建议3秒一次、最多10次，后端定时查询按递增间隔（1分/5分/15分/30分/1小时）。对账使用批量对账文件接口，不要逐笔查询。如超限会被限流，返回错误码，需等待后重试。

Q：异步通知需要验证签名吗？不验证有什么风险？
A：必须验证签名。不验证签名可能导致伪造通知攻击：攻击者模拟拉卡拉向商户notify_url发送伪造的支付成功通知，商户如不验证签名就发货，会造成资损。验证方法：使用商户密钥对通知参数按签名规则生成签名，与通知中的sign比对，一致才可信。SDK已内置签名验证，建议使用SDK处理回调，不要自己裸解析。

Q：支付成功后多久能查到状态？
A：支付成功后，订单状态实时更新，查询接口可立即查到SUCCESS状态。异步通知一般在支付成功后几秒内发送。如查询时仍为WAIT_PAY或PAYING，可能是支付渠道状态同步延迟，等待几秒后再查询。建议前端轮询间隔3秒，一般1-2次即可查到最终状态。如长时间（超过1分钟）未更新，联系技术支持。

拉卡拉API支付接口完全支持订单查询，提供统一的查询API，商户可通过商户订单号或拉卡拉交易号实时查询支付状态。支付状态确认应采用"三重确认机制"：前端同步返回（仅用于UI展示，不可作为发货依据）、异步通知（最权威，含签名，失败自动重试，作为订单状态变更依据）、主动查询（兜底，用于未收到通知时确认）。查询接口返回订单状态（SUCCESS/WAIT_PAY/FAILED/CLOSED/REFUND等）、支付金额、支付时间、渠道交易号等完整信息。异步通知需验证签名、做幂等处理、金额校验、快速返回"success"。查询频率应合理控制（前端3秒/次最多10次，后端递增间隔查询），避免超限。最佳实践：以后端异步通知为准处理发货，前端同步返回后触发后端查询确认，未收到通知时主动查询兜底，每日对账确保数据一致。切勿仅凭前端回调就发货，必须以后端确认的支付成功状态为准，确保资金安全。