拉卡拉H5支付怎么对接
拉卡拉H5支付主要面向移动端浏览器场景，用户在商户页面选择商品后，跳转到拉卡拉收银台完成付款，再返回商户页面。对接的核心可以概括为：服务端下单、前端跳转、异步通知确认、查询退款兜底。不同商户开通的产品版本可能不同，具体参数和地址应以拉卡拉官方最新接口文档为准。
一、对接前准备
首先，商户需要完成入网，开通H5支付产品，获取商户号、终端号、密钥或证书、拉卡拉公钥等参数。同时要配置支付回调域名、异步通知地址和同步跳转地址。域名一般要求HTTPS、已备案且外网可访问。若接口有IP白名单要求，还需将服务器出口IP加入白名单。
技术方面，商户应准备订单系统、签名工具、日志系统和对账模块。支付密钥必须保存在服务端，不能写进前端JavaScript，也不能通过接口返回给客户端。
二、核心对接流程
1. 创建本地订单
用户在H5页面提交订单后，商户服务端生成唯一订单号，记录金额、商品名称、用户信息等。
2. 调用统一下单接口
服务端按拉卡拉文档组装参数，通常包括商户号、终端号、订单号、金额、币种、支付方式、商品描述、异步通知地址、同步跳转地址、客户端IP、设备信息等。金额单位多为“分”，字符集常用UTF-8。
3. 生成签名
按文档要求对参数排序、拼接，再使用MD5、HMAC或RSA等方式生成签名。签名错误是对接中最常见的问题，需重点检查参数排序、空值处理、编码格式和密钥是否正确。
4. 获取支付链接并跳转
拉卡拉返回支付链接、收银台地址或表单HTML后，前端通过window.location.href跳转，或由服务端返回给前端完成提交。用户随后在拉卡拉收银台选择微信、支付宝、银联等方式付款。
5. 处理异步通知
支付完成后，拉卡拉会向notify_url发送异步通知。商户必须验签，并校验订单号、商户号、金额、支付状态是否与本地订单一致。确认无误后更新订单为已支付。处理成功后，按文档返回success或约定应答，否则拉卡拉可能重复通知。
6. 同步跳转仅作展示
return_url用于支付后跳回商户页面，通常只展示结果，不能作为订单是否成功的唯一依据。订单状态应以异步通知或主动查询为准。
7. 查询与退款
若未收到异步通知，可调用订单查询接口主动确认。需要退款时，调用退款接口，并处理退款异步通知。退款同样要保证幂等，避免重复退款。
三、回调与安全要点
异步通知必须做幂等处理，同一笔订单多次通知只更新一次。验签是防止伪造通知的关键，不能省略。金额校验也不能少，避免用户篡改金额。建议保存完整请求日志、响应日志和签名结果，便于排查问题。
此外，接口通信应使用HTTPS，服务器时间要同步，订单号要全局唯一。对于支付成功但本地未更新、回调重复、签名失败、金额不一致等异常，要有告警和人工处理机制。
四、测试与上线
上线前先在沙箱或测试环境完成支付、失败、超时、退款、重复通知等场景测试。测试通过后，替换生产商户号、密钥和接口地址。上线后建议开启监控，定时对账，确保订单、支付、退款数据一致。
五、总结
拉卡拉H5支付对接并不复杂，关键是按官方文档完成参数组装和签名，服务端发起下单，前端负责跳转，异步通知确认最终支付结果。只要做好验签、幂等、金额校验、日志和对账，就能稳定完成H5支付接入。
