拉卡拉API支付接口支持扫码支付吗?主扫被扫模式接入流程与参数配置详解

扫码支付是目前最主流的支付方式之一，覆盖微信、支付宝、银联等多个渠道。对于需要在自己的平台或系统中集成支付能力的企业来说，通过API接口接入扫码支付是最灵活高效的方式。拉卡拉作为央行持牌支付机构，其API支付接口是否支持扫码支付？主扫和被扫模式有什么区别？如何接入和配置？本文将详细解析拉卡拉API支付接口的扫码支付能力、主扫被扫模式实现原理、接入流程、接口参数配置，以及常见问题和最佳实践。

核心结论：拉卡拉API支付接口完全支持扫码支付，同时支持主扫模式（用户扫商户码）和被扫模式（商户扫用户付款码）。通过统一的API接口可接入微信、支付宝、银联等主流扫码渠道，一次接入多渠道通用。主扫模式适用于线上场景（APP/网站/小程序），被扫模式适用于线下场景（门店收银）。接口采用RESTful风格，JSON格式，提供Java/Python/Go等多语言SDK，支持沙箱测试，接入流程清晰，参数配置规范。

1. 拉卡拉API支付接口支持扫码支付吗？

 

扫码支付主扫被扫模式对比：主扫（用户扫商户码）vs 被扫（商户扫用户付款码），适用场景与交互方式对比

支持。拉卡拉API支付接口提供完整的扫码支付能力，覆盖微信、支付宝、银联云闪付等主流扫码渠道。

1.1 支持的扫码渠道

渠道	主扫/被扫	说明
微信支付	主扫+被扫	支持微信扫码支付（Native/付款码），覆盖微信生态用户
支付宝	主扫+被扫	支持支付宝扫码支付（当面付/付款码），覆盖支付宝用户
银联云闪付	主扫+被扫	支持银联二维码支付，覆盖云闪付APP及各大银行APP
数字人民币	主扫+被扫	支持数字人民币扫码支付（视开通情况）

1.2 扫码支付的两种模式

扫码支付分为主扫和被扫两种模式，适用于不同场景：

1.2.1 主扫模式（用户扫商户码）

• 定义：商户系统生成支付二维码，用户使用微信/支付宝等APP扫描二维码完成支付

• 适用场景：线上电商、APP支付、网站支付、小程序支付、线下固定二维码收款

• 交互流程：用户下单→商户调用API生成二维码→用户扫码→用户确认支付→支付完成回调

• 特点：用户主动操作，无需商户硬件设备，适合线上和自助场景

1.2.2 被扫模式（商户扫用户付款码）

• 定义：用户在APP中调出付款码，商户使用扫码枪或扫码设备扫描用户付款码完成支付

• 适用场景：线下门店收银、商超、餐饮、便利店等有收银台的场景

• 交互流程：用户出示付款码→商户扫码设备读取→商户调用API提交支付→支付完成（免密或需用户确认）

• 特点：商户主动操作，支付速度快，适合线下收银场景，需要扫码设备

2. 主扫模式接入详解

2.1 接入流程

1. 商户下单：用户在商户平台（APP/网站/小程序）选择商品并下单

2. 调用统一下单API：商户后端调用拉卡拉扫码支付下单接口，传入商户订单号、金额、商品描述、支付渠道等参数

3. 获取支付二维码：拉卡拉返回支付二维码链接（code_url）或二维码图片

4. 展示二维码：商户前端将二维码展示给用户（网页显示二维码图片，APP可生成二维码）

5. 用户扫码支付：用户使用微信/支付宝扫描二维码，确认支付

6. 支付结果回调：支付完成后，拉卡拉异步回调商户配置的通知地址，告知支付结果

7. 商户处理结果：商户收到回调后更新订单状态，给用户发货或提供服务

8. 主动查询（可选）：如未收到回调，商户可主动调用查询接口确认支付状态

2.2 关键接口参数

2.2.1 下单请求参数

参数名	类型	必填	说明
merchant_no	String	是	商户号，拉卡拉分配的唯一商户标识
out_trade_no	String	是	商户订单号，商户系统内唯一，32字符以内
total_amount	Number	是	支付金额，单位分，整数类型
subject	String	是	商品标题/订单标题，展示在用户支付页面
pay_type	String	是	支付渠道：wechat（微信）/alipay（支付宝）/unionpay（银联）
notify_url	String	是	支付结果异步通知地址，需公网可访问
return_url	String	否	支付完成后跳转地址（网页支付场景）
client_ip	String	否	用户端IP地址，用于风控
timeout_express	String	否	订单超时时间，如30m（30分钟），超时自动关闭
extend_params	Object	否	扩展参数，如分账参数、行业参数等

2.2.2 下单响应参数

• code：响应码，0表示成功

• message：响应信息

• trade_no：拉卡拉交易号，唯一标识该笔支付

• code_url：支付二维码链接，商户可生成二维码图片展示给用户

• qr_code：二维码图片URL（部分渠道直接返回图片）

• out_trade_no：商户订单号（回传）

2.3 二维码生成与展示

• 获取code_url：下单接口返回code_url（如weixin://wxpay/bizpayurl?pr=xxx）

• 生成二维码图片：使用二维码生成库（如Java的ZXing、Python的qrcode、前端的qrcode.js）将code_url生成二维码图片

• 前端展示：网页端用img标签展示，APP端用ImageView展示，小程序端用image组件展示

• 二维码有效期：一般为2小时，超时未支付订单自动关闭，需重新下单

3. 被扫模式接入详解

3.1 接入流程

1. 用户出示付款码：用户在微信/支付宝/云闪付APP中调出付款码（条形码+二维码）

2. 商户扫码：收银员使用扫码枪或扫码设备扫描用户付款码，获取付款码内容（auth_code）

3. 调用付款码支付API：商户系统调用拉卡拉付款码支付接口，传入auth_code、订单号、金额等参数

4. 支付处理：拉卡拉将支付请求转发给对应渠道（微信/支付宝），渠道验证付款码并扣款

5. 返回支付结果：接口同步返回支付结果（成功/失败/需用户输入密码）

6. 结果处理：商户根据返回结果更新订单状态，成功则完成交易，失败则提示用户

7. 异步回调：支付完成后也会异步回调通知地址（与主扫相同）

3.2 关键接口参数

3.2.1 付款码支付请求参数

参数名	类型	必填	说明
merchant_no	String	是	商户号
out_trade_no	String	是	商户订单号
total_amount	Number	是	支付金额，单位分
auth_code	String	是	用户付款码内容（扫码枪读取的18位数字）
subject	String	是	商品标题
notify_url	String	是	异步通知地址
scene	String	否	支付场景，如bar_code（条码支付）

3.2.2 付款码支付响应

• 支付成功：直接返回成功，交易完成

• 需用户确认：返回"支付中"状态，用户需在APP中输入密码或确认，此时需轮询查询或等待回调

• 支付失败：返回失败原因（如付款码过期、余额不足、账户异常等）

3.3 被扫模式注意事项

• 付款码有效期：用户付款码每分钟刷新一次，扫码后需尽快提交支付，超时会失败

• 免密额度：小额支付（一般1000元以下）可免密直接支付，超额需用户输入密码

• 扫码设备：需支持读取微信/支付宝付款码的扫码枪或扫码盒子，一般USB接口即插即用

• 支付速度：被扫模式支付速度快（一般1-3秒），适合线下高频收银场景

• 错误处理：付款码过期、用户取消、余额不足等情况需有友好提示和重试机制

4. API接入架构与配置

 

扫码支付API接入架构：商户系统→拉卡拉支付网关→微信/支付宝/银联渠道，含下单/扫码/回调/查询接口

4.1 接入架构

拉卡拉扫码支付API采用统一网关架构，商户只需对接拉卡拉一套接口，即可同时支持微信、支付宝、银联等多个渠道：

• 商户系统层：商户的APP/网站/小程序/收银系统，负责发起支付请求和展示支付界面

• 拉卡拉网关层：统一API入口，负责参数校验、签名验证、路由分发、交易处理

• 渠道层：微信/支付宝/银联等支付渠道，负责实际的资金扣款和用户交互

• 回调通知：支付结果通过异步回调通知商户系统

• 查询接口：商户可主动查询支付状态，作为回调的补充

4.2 接入前准备

1. 开通商户号：在拉卡拉开通支付商户号，完成企业资质审核和签约

2. 开通扫码支付：在商户后台开通扫码支付产品，选择需要的支付渠道（微信/支付宝/银联）

3. 获取API密钥：在商户后台获取商户号、API密钥（app_key/app_secret），用于接口签名

4. 配置回调地址：配置支付结果异步通知地址（notify_url），需公网可访问的HTTPS地址

5. 下载SDK和文档：下载API文档和对应语言的SDK（Java/Python/Go）

6. 沙箱测试：在沙箱环境完成接口联调，验证支付流程

4.3 签名机制

• 签名算法：使用RSA2或MD5签名（根据接口要求）

• 签名规则：将请求参数按ASCII码排序，拼接成key=value&key=value格式，加上密钥后进行签名

• 签名验证：拉卡拉验证请求签名，商户也需验证回调通知的签名，防止伪造

• 密钥管理：API密钥需妥善保管，不要暴露在前端代码中，定期更换

4.4 沙箱测试

• 沙箱环境：拉卡拉提供独立的沙箱测试环境，与生产环境隔离

• 测试账号：沙箱环境使用测试商户号和测试密钥

• 模拟支付：沙箱环境可模拟支付成功/失败/超时等场景，无需真实资金

• 联调验证：在沙箱中验证下单、二维码生成、回调通知、查询等完整流程

• 上线切换：沙箱测试通过后，切换到生产环境的商户号和密钥即可正式上线

5. 异步通知与订单查询

5.1 异步通知机制

• 通知触发：支付完成（成功或失败）后，拉卡拉向商户配置的notify_url发送POST通知

• 通知内容：包含商户订单号、拉卡拉交易号、支付金额、支付状态、支付时间、渠道交易号等

• 签名验证：通知包含签名，商户需验证签名确保通知来自拉卡拉

• 通知重试：商户需返回"success"表示收到，否则拉卡拉会重试通知（一般重试8次，间隔递增）

• 幂等处理：商户需对同一订单的多次通知做幂等处理，避免重复发货

5.2 订单查询接口

• 查询方式：通过商户订单号（out_trade_no）或拉卡拉交易号（trade_no）查询

• 查询内容：返回订单状态（待支付/支付成功/已关闭/已退款）、支付金额、支付时间、渠道信息等

• 使用场景：未收到异步通知时主动查询、用户支付页面轮询、对账时核实订单状态

• 查询频率：合理控制查询频率，避免频繁调用

6. 主扫与被扫模式选择建议

对比维度	主扫模式	被扫模式
适用场景	线上APP/网站/小程序、线下自助收款	线下门店收银、商超、餐饮、便利店
交互方式	用户扫商户二维码	商户扫用户付款码
硬件要求	无需特殊硬件，手机即可	需要扫码枪或扫码设备
支付速度	较快（扫码即支付，1-3秒）
用户体验	用户主动操作，体验较好	商户操作，用户只需出示码
风控等级	用户确认支付，风控较宽松	免密支付有额度限制，超额需密码
接入复杂度	需生成和展示二维码	需对接扫码设备读取付款码

选择建议：线上场景（APP/网站/小程序）优先选择主扫模式，用户体验好且无需额外硬件。线下有收银台的门店场景优先选择被扫模式，支付速度快、收银效率高。如果同时有线上和线下场景，可两种模式都接入，根据场景自动切换。拉卡拉API统一支持两种模式，一次接入即可同时使用。

7. 常见问题解答

Q：接入拉卡拉扫码支付需要单独对接微信和支付宝吗？
A：不需要。拉卡拉作为聚合支付机构，提供统一的API接口，商户只需对接拉卡拉一套接口，即可同时支持微信、支付宝、银联等多个渠道。拉卡拉负责与各渠道的对接和维护，商户无需分别申请各渠道的商户号。

Q：主扫模式的二维码有效期是多久？
A：一般为2小时（具体以接口返回为准）。用户扫码后需在有效期内完成支付，超时订单自动关闭。如二维码过期，用户扫码会提示订单已过期，商户需重新下单生成新二维码。建议设置合理的订单超时时间（如30分钟），避免长期占用。

Q：被扫模式用户付款码扫了但支付失败怎么办？
A：付款码支付失败可能有多种原因：付款码过期（每分钟刷新）、用户余额不足、账户异常、网络问题等。商户系统应根据接口返回的错误码给出相应提示，让用户刷新付款码后重试，或更换支付方式。失败的订单不会扣款，无需担心重复支付。

Q：扫码支付的费率是多少？
A：扫码支付费率一般为0.38%-0.6%，具体费率根据商户行业、交易量、接入渠道等因素确定，需与拉卡拉商务团队沟通。微信和支付宝的费率可能不同，银联二维码费率也有差异。建议在签约时明确各渠道费率。

Q：可以同时支持微信和支付宝的二维码吗？
A：可以。拉卡拉支持聚合二维码（一码多付），一个二维码同时支持微信和支付宝扫码，用户用哪个APP扫就调起哪个支付。也可以分别生成微信和支付宝的独立二维码。聚合码用户体验更好，推荐使用。

Q：扫码支付支持分账吗？
A：支持。拉卡拉扫码支付可与分账通/钱账通联动，在支付下单时传入分账参数，支付成功后自动执行分账。支持比例分账、固定金额分账、平台手续费等多种分账模式，实现支付和分账一体化。

Q：沙箱环境可以测试真实扫码支付吗？
A：沙箱环境使用模拟支付，不需要真实资金。可以模拟支付成功、失败、超时等场景，验证接口调用和业务流程。正式上线前需在生产环境用小额真实支付验证（如支付0.01元）。

Q：回调通知收不到怎么办？
A：首先检查notify_url是否为公网可访问的HTTPS地址，服务器防火墙是否放行拉卡拉回调IP。其次检查回调处理是否正确返回"success"。如仍收不到，可使用订单查询接口主动查询支付状态作为补充。建议同时实现异步回调和主动查询，确保支付状态可靠。

Q：扫码支付有交易限额吗？
A：有。扫码支付的限额由支付渠道（微信/支付宝）和拉卡拉共同决定，一般单笔限额5万元，单日限额根据商户资质确定。用户端也有支付限额（如微信零钱限额、银行卡限额）。大额支付建议使用其他支付方式或分笔支付。

Q：接入扫码支付需要多长时间？
A：从申请到上线一般需要1-2周。其中商户开通和资质审核1-3天，技术对接和沙箱测试3-7天（取决于开发能力），生产环境验证1-2天。使用拉卡拉提供的SDK可加快对接速度，简单场景可能3-5天即可上线。

拉卡拉API支付接口提供完整的扫码支付能力，同时支持主扫和被扫两种模式，覆盖微信、支付宝、银联等主流渠道。主扫模式适合线上场景，用户扫码支付；被扫模式适合线下收银，商户扫用户付款码。两种模式共用统一的API架构，接入流程清晰，参数配置规范，提供多语言SDK和沙箱测试环境。商户只需对接拉卡拉一套接口，即可实现多渠道扫码支付，并可与分账功能联动实现支付分账一体化。无论是线上电商还是线下门店，都能找到适合的扫码支付方案。

本文接口参数和流程基于拉卡拉API支付接口公开信息整理，具体接口名称、参数名、签名方式以实际接入的API文档为准。建议接入前下载最新版API文档，并在沙箱环境完成联调测试。