LINE Pay 商家扫码支付前端接入说明

适用端：Foodie 商家 App（uni-app）

场景：客户出示 LINE Pay My Code，商家 App 扫码收款

1. 前端整体流程

按以下顺序接入：

商家端创建订单，支付方式传 paymentMethod="3"。
订单必须只有一个门店。
商家点击“LINE Pay 扫码收款”。
前端调用 uni.scanCode 扫描客户出示的 LINE Pay My Code。
扫码结果必须是 18 位数字，即 oneTimeKey。
前端把订单号 ddId 和 oneTimeKey 提交给扫码付款接口。
根据付款接口返回的 status 展示当前状态。
如果状态是处理中，定时调用状态查询接口。
只有后端返回 PAID，才能提示商家“收款成功”。

2. 商家创建订单

调用现有接口：

POST /system/orderShOprate/createOrder
Header: token

前端只需注意：

paymentMethod 必须传字符串 "3"。
items 只能有一个门店。
创建成功后取得订单号 ddId。
只有这个接口创建的商家订单可以使用扫码付款。

商品、金额、备注、发票等字段继续使用商家端现有下单格式，不需要为 LINE Pay 新增字段。

3. 扫描客户付款码

前端调用 uni-app 扫码方法：

uni.scanCode

需要支持：

条形码。
二维码。
扫码结果必须匹配 18 位数字。

扫码得到的内容作为 oneTimeKey。

注意：

不要打印 oneTimeKey。
不要保存到本地缓存或数据库。
不要把它放到页面 URL。
每次客户重新生成 My Code 后，都要重新扫码。

4. 提交扫码付款

POST /system/orderShOprate/linePay/offline/pay
Header: token
Content-Type: application/json

请求参数：

{
  "ddId": "202608180001",
  "oneTimeKey": "123456789012345678"
}

字段	类型	说明
`ddId`	string	商家端创建的订单号
`oneTimeKey`	string	扫描得到的 18 位 LINE Pay My Code

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "ddId": "202608180001",
    "paymentId": 84,
    "lineOrderId": "LPOFF123456789",
    "transactionId": "2026081800000000001",
    "status": "AUTH_REQUIRED",
    "reusedAttempt": false,
    "updatedAt": "2026-08-18T12:34:56+08:00"
  }
}

前端主要使用：

status：判断付款状态。
reusedAttempt：判断后端是否复用了已有支付记录。
transactionId：仅用于展示或排查，必须作为字符串处理。

reusedAttempt=true 表示订单已经有一笔付款正在处理。本次新扫描的付款码没有再次发送给 LINE，前端直接查询原付款状态，不要再次扫码或提交付款。

5. 查询付款状态

GET /system/orderShOprate/linePay/offline/status?ddId=202608180001
Header: token

响应 data 与付款接口基本相同，前端继续读取 data.status。

查询时机：

付款接口返回 AUTH_REQUIRED。
付款接口返回 PROCESSING。
App 从后台回到前台。
商家重新打开订单详情。
付款接口发生网络超时。

建议处理中每 5 秒查询一次。页面退出后停止轮询；重新进入页面时再查询一次。

6. 状态处理

`status`	含义	前端操作
`AUTH_REQUIRED`	客户需要在 LINE Pay 完成选择付款方式或认证	提示客户在 LINE Pay 完成操作，继续查询状态，不允许重新扫码
`PROCESSING`	后端正在确认付款结果	显示“支付结果确认中”，继续查询状态，不允许重新扫码
`PAID`	付款成功	停止查询，提示商家收款成功，刷新订单
`CANCELLED`	客户取消或付款码过期	停止查询，允许客户生成新的 My Code 后重新扫码
`FAILED`	付款明确失败	停止查询，允许客户生成新的 My Code 后重新扫码
`MANUAL_REVIEW`	金额异常或付款结果需要人工核对	停止查询，提示联系平台处理，不允许重新扫码

前端必须遵守：

扫码成功不等于付款成功。
HTTP 请求成功不等于付款成功。
存在 transactionId 不等于付款成功。
只有 status="PAID" 才是收款成功。

7. 网络异常处理

付款接口超时

如果 /offline/pay 超时或断网：

不要自动重发付款接口。
不要重新使用刚才的 oneTimeKey。
网络恢复后调用 /offline/status 查询订单状态。
根据状态查询结果继续处理。

原因是 LINE 可能已经收到付款请求，重复提交可能造成重复付款风险。

状态查询失败

提示“支付结果暂时无法确认，请稍后查询”。
不要直接显示付款失败。
不要自动重新扫码。
商家重新进入订单页面后再次查询。

8. 接口错误处理

项目接口统一返回：

{
  "code": 500,
  "msg": "业务错误信息"
}

code === 200：读取 data。
code !== 200：展示后端返回的 msg。
不要根据中文 msg 判断付款状态。
付款状态只根据成功响应中的 data.status 判断。

9. Sandbox 联调步骤

Online API v4 和 Offline API v4 共用现有 Channel ID / Channel Secret，不需要重新注册 Sandbox。

测试步骤：

后端使用 Sandbox 环境。
测试门店已经录入并启用 Channel ID / Channel Secret。
商家端创建 paymentMethod="3" 的单门店订单。

打开台湾 Sandbox My Code 生成器：

https://sandbox-web-pay.line.me/web/sandbox/payment/oneTimeKey?countryCode=TW&paymentMethod=balance

商家 App 扫描生成的测试付款码。
调用 /offline/pay。
如果返回处理中，继续调用 /offline/status。
最终返回 PAID 后提示收款成功。

Sandbox 环境不能使用客户真实 LINE App 生成的 My Code。

10. 前端验收清单

商家下单时 paymentMethod="3"。
一笔订单只有一个门店。
使用 uni.scanCode 扫描条形码和二维码。
扫码结果必须为 18 位数字。
oneTimeKey 不记录、不缓存、不打印。
提交付款期间禁用重复扫码。
AUTH_REQUIRED 和 PROCESSING 会继续查询状态。
只有 PAID 提示收款成功。
CANCELLED 和 FAILED 才允许重新扫码。
MANUAL_REVIEW 不允许重新扫码。
付款接口超时后不自动重发，只查询状态。
App 回到前台或重新进入订单页面时重新查询状态。

11. 接口汇总

操作	方法	接口
商家创建订单	POST	`/system/orderShOprate/createOrder`
提交扫码付款	POST	`/system/orderShOprate/linePay/offline/pay`
查询付款状态	GET	`/system/orderShOprate/linePay/offline/status?ddId={ddId}`

merchant-offline-app-integration.md 6.7 KB Bezpośredni odnośnik Historia Czysty