|
|
@@ -3,8 +3,8 @@
|
|
|
**适用对象**：用户端 App（uni-app）前端开发人员
|
|
|
**接口版本**：`specs/020-omg-payment-rebuild` 新实现
|
|
|
**当前环境**：OMG 测试环境
|
|
|
-**支付方式目标**：OMG 官方页面优先展示信用卡、Apple Pay
|
|
|
-**更新时间**：2026-08-14
|
|
|
+**支付方式目标**：App 只提供信用卡、Apple Pay，OMG 直接进入所选渠道
|
|
|
+**更新时间**：2026-08-18
|
|
|
|
|
|
> 本文只描述当前新 OMG 实现。`specs/016-omg-payment` 中的旧 Controller、旧流水、旧退款和旧前端文档已经退役，不得作为接入依据。
|
|
|
|
|
|
@@ -13,13 +13,14 @@
|
|
|
OMG 是网页托管式收银台，App 不需要接入 OMG SDK。前端只需要完成以下流程：
|
|
|
|
|
|
1. 创建订单时把 OMG 支付方式设置为 `payType = "2"`。
|
|
|
-2. 调用 `POST /pay/omg/create` 获取 `gatewayUrl` 和完整的 `formFields`。
|
|
|
-3. 在当前 App WebView 页面中，把所有 `formFields` 原样以 HTML Form POST 到 `gatewayUrl`。
|
|
|
-4. 用户付款后，OMG 将浏览器 POST 到后端 `/pay/omg/result`；后端验证返回资料后，优先通过 uni-app Bridge 打开支付结果页，Bridge 不可用时再通过 App Scheme 兜底。
|
|
|
-5. App 结果页取得 `ddId`，调用 `POST /pay/omg/query` 确认最终支付状态。
|
|
|
-6. 只有 query 返回 `status = "PAID"` 才能展示支付成功。
|
|
|
+2. 在 App 自有界面让用户选择信用卡或 Apple Pay，分别使用 `paymentMethod = "CREDIT"` 或 `"APPLE_PAY"`。
|
|
|
+3. 调用 `POST /pay/omg/create` 获取所选渠道的 `gatewayUrl` 和完整 `formFields`。
|
|
|
+4. 在当前 App WebView 页面中，把所有 `formFields` 原样以 HTML Form POST 到 `gatewayUrl`。
|
|
|
+5. 用户付款后，OMG 将浏览器 POST 到后端 `/pay/omg/result`；后端验证返回资料后，优先通过 uni-app Bridge 打开支付结果页，Bridge 不可用时再通过 App Scheme 兜底。
|
|
|
+6. App 结果页取得 `ddId`，调用 `POST /pay/omg/query` 确认最终支付状态。
|
|
|
+7. 只有 query 返回 `status = "PAID"` 才能展示支付成功。
|
|
|
|
|
|
-本次渠道过滤由后端表单完成。App 顶层仍然只显示“OMG 支付”和“LINE Pay”，不增加“信用卡/Apple Pay”二级选择页面，也不接入原生 Apple Pay SDK。
|
|
|
+App 需要新增“信用卡 / Apple Pay”选择，但不接入原生 Apple Pay SDK。后端只接受两个稳定枚举并生成单渠道签名表单，因此 OMG 页面不会再展示超商快付、AFTEE 或其他渠道选择项。用户可见文案必须接入 App 现有 i18n。
|
|
|
|
|
|
当前测试环境不支持退款。`POST /pay/omg/refund` 只会返回“测试环境不支持退款”，不会发起真实退款，也不会修改订单。
|
|
|
|
|
|
@@ -27,16 +28,19 @@ OMG 是网页托管式收银台，App 不需要接入 OMG SDK。前端只需要
|
|
|
|
|
|
```text
|
|
|
[App 创建订单，payType="2"]
|
|
|
+ |
|
|
|
+ v
|
|
|
+[App 选择 CREDIT / APPLE_PAY]
|
|
|
|
|
|
|
| POST /pay/omg/create
|
|
|
| Header: token
|
|
|
- | Body: {"orderId":"..."}
|
|
|
+ | Body: {"orderId":"...","paymentMethod":"..."}
|
|
|
v
|
|
|
[后端返回 gatewayUrl + formFields]
|
|
|
|
|
|
|
| 当前 WebView 原样 Form POST
|
|
|
v
|
|
|
-[OMG 测试收银台：优先显示信用卡 / Apple Pay]
|
|
|
+[OMG 测试环境：直接进入所选付款流程]
|
|
|
|
|
|
|
+-------------------------------+
|
|
|
| |
|
|
|
@@ -117,12 +121,14 @@ token 只发送给本项目后端，绝对不能放入 OMG Form，也不能发
|
|
|
|
|
|
### 3.4 订单号字段
|
|
|
|
|
|
-接口请求统一使用：
|
|
|
+create/retry 请求使用：
|
|
|
|
|
|
```json
|
|
|
-{"orderId":"业务订单号"}
|
|
|
+{"orderId":"业务订单号","paymentMethod":"CREDIT 或 APPLE_PAY"}
|
|
|
```
|
|
|
|
|
|
+query/refund 请求仍使用 `{"orderId":"业务订单号"}`。
|
|
|
+
|
|
|
后端 App Scheme 回跳参数使用：
|
|
|
|
|
|
```text
|
|
|
@@ -141,7 +147,8 @@ Content-Type: application/json
|
|
|
token: <用户登录 token>
|
|
|
|
|
|
{
|
|
|
- "orderId": "991786433092835"
|
|
|
+ "orderId": "991786433092835",
|
|
|
+ "paymentMethod": "CREDIT"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
@@ -154,7 +161,7 @@ token: <用户登录 token>
|
|
|
- 订单门店已启用有效 OMG 凭证。
|
|
|
- 同一订单当前不能存在另一个未结束的 OMG 支付尝试。
|
|
|
|
|
|
-客户端只能传 `orderId`。金额、商户号、回调地址、网关地址、付款渠道和签名都由后端决定。
|
|
|
+create/retry 只能传 `orderId` 与 `paymentMethod`；`paymentMethod` 仅允许 `CREDIT/APPLE_PAY`。query/refund 仍只传 `orderId`。金额、商户号、回调地址、网关地址、OMG 原始付款参数和签名都由后端决定。
|
|
|
|
|
|
### 4.2 成功响应
|
|
|
|
|
|
@@ -177,8 +184,8 @@ token: <用户登录 token>
|
|
|
"ItemName": "Order 991786433092835",
|
|
|
"ReturnURL": "https://foodieapi.waimai-paotui.com/pay/omg/notify",
|
|
|
"OrderResultURL": "https://foodieapi.waimai-paotui.com/pay/omg/result",
|
|
|
- "ChoosePayment": "ALL",
|
|
|
- "IgnorePayment": "ATM#CVS#BarcodeATM",
|
|
|
+ "ChoosePayment": "Credit",
|
|
|
+ "UnionPay": "2",
|
|
|
"EncryptType": "1",
|
|
|
"InvoiceMark": "N",
|
|
|
"NeedExtraPaidInfo": "Y",
|
|
|
@@ -188,6 +195,8 @@ token: <用户登录 token>
|
|
|
}
|
|
|
```
|
|
|
|
|
|
+上例为信用卡响应。Apple Pay 响应的 `ChoosePayment` 为 `ApplePay`，且不包含 `UnionPay` 或 `IgnorePayment`。后端不会返回 `ChoosePayment=ALL`。
|
|
|
+
|
|
|
字段说明：
|
|
|
|
|
|
| 字段 | 类型 | App 用法 |
|
|
|
@@ -197,8 +206,8 @@ token: <用户登录 token>
|
|
|
| `formFields` | object | 所有键值都必须原样创建为隐藏 input 并 POST |
|
|
|
| `MerchantTradeNo` | string | 后端生成的 OMG 交易编号；前端只透传，不作为业务订单号 |
|
|
|
| `TotalAmount` | string | 后端根据订单金额生成；前端不得修改 |
|
|
|
-| `ChoosePayment` | string | 当前固定 `ALL`，使用 OMG 官方付款方式选择页面；前端不得修改 |
|
|
|
-| `IgnorePayment` | string | 当前固定 `ATM#CVS#BarcodeATM`，由 OMG 隐藏 ATM、CVS 和 BarcodeATM；前端不得修改 |
|
|
|
+| `ChoosePayment` | string | 后端按 `paymentMethod` 生成 `Credit` 或 `ApplePay`；前端不得修改 |
|
|
|
+| `UnionPay` | string | 仅信用卡表单存在且固定为 `2`，用于隐藏银联；Apple Pay 表单不包含该字段 |
|
|
|
| `ReturnURL` | string | OMG 服务端付款通知地址；前端不调用 |
|
|
|
| `OrderResultURL` | string | OMG 浏览器付款结果地址；前端不直接调用 |
|
|
|
| `CheckMacValue` | string | 表单签名；修改任意已签名字段都会导致 OMG 拒绝 |
|
|
|
@@ -251,7 +260,7 @@ function submitOmgForm(gatewayUrl, formFields) {
|
|
|
发起页示例：
|
|
|
|
|
|
```js
|
|
|
-async function startOmgPayment(orderId) {
|
|
|
+async function startOmgPayment(orderId, paymentMethod) {
|
|
|
if (this.omgSubmitting) return;
|
|
|
this.omgSubmitting = true;
|
|
|
|
|
|
@@ -260,7 +269,7 @@ async function startOmgPayment(orderId) {
|
|
|
url: '/pay/omg/create',
|
|
|
method: 'POST',
|
|
|
header: { token: uni.getStorageSync('token') },
|
|
|
- data: { orderId }
|
|
|
+ data: { orderId, paymentMethod }
|
|
|
});
|
|
|
|
|
|
if (response.code !== 200) {
|
|
|
@@ -311,6 +320,7 @@ submitOmgForm(payload.gatewayUrl, payload.formFields);
|
|
|
| `ORDER_ALREADY_PAID` | 订单已经付款 | 进入订单结果页并刷新状态 |
|
|
|
| `ORDER_AMOUNT_INVALID` | 订单金额异常 | 展示后端 `msg` |
|
|
|
| `PAYMENT_TYPE_INVALID` | 订单 `payType` 不是 `"2"` | 检查创建订单时的支付方式 |
|
|
|
+| `PAYMENT_METHOD_INVALID` | `paymentMethod` 缺失或不是 `CREDIT/APPLE_PAY` | 停止支付并检查 App 渠道映射 |
|
|
|
| `STORE_CREDENTIAL_UNAVAILABLE` | 门店未启用有效 OMG 凭证 | 展示后端 `msg` |
|
|
|
| `PAYMENT_ATTEMPT_EXISTS` | 已有未结束的支付尝试 | 用户确认重新支付时调用 `/pay/omg/retry`，不要循环调用 create |
|
|
|
| `PAYMENT_CONFIGURATION_INVALID` | 后端测试网关或回调配置不合法 | 展示后端 `msg`，通知后端排查 |
|
|
|
@@ -513,7 +523,8 @@ Content-Type: application/json
|
|
|
token: <用户登录 token>
|
|
|
|
|
|
{
|
|
|
- "orderId": "991786433092835"
|
|
|
+ "orderId": "991786433092835",
|
|
|
+ "paymentMethod": "APPLE_PAY"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
@@ -543,17 +554,17 @@ retry 成功响应与 create 完全相同。App 收到后创建新的支付 WebV
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-`paymentType` 是 OMG 查询结果，不是 App 传参，也不要求 App 增加“信用卡/Apple Pay”二级选择。用户界面仍然只有“OMG 支付”和“LINE Pay”。
|
|
|
+`paymentType` 是 OMG 查询结果，不是 App 传参；`paymentMethod` 才是 App 本次选择并提交给 create/retry 的受控枚举。用户重新支付时可以重新选择信用卡或 Apple Pay。
|
|
|
|
|
|
App 推荐处理：
|
|
|
|
|
|
```js
|
|
|
-async function retryOmgPayment(orderId) {
|
|
|
+async function retryOmgPayment(orderId, paymentMethod) {
|
|
|
const response = await request({
|
|
|
url: '/pay/omg/retry',
|
|
|
method: 'POST',
|
|
|
header: { token: uni.getStorageSync('token') },
|
|
|
- data: { orderId }
|
|
|
+ data: { orderId, paymentMethod }
|
|
|
});
|
|
|
|
|
|
if (response.code === 200) {
|
|
|
@@ -651,7 +662,7 @@ token: <用户登录 token>
|
|
|
10. `tradeNo`、`merchantTradeNo` 始终按字符串处理，不转换为 JavaScript Number。
|
|
|
11. query 会访问 OMG 网关，不做高频轮询。
|
|
|
12. `PAYMENT_ATTEMPT_EXISTS` 不能靠重复调用 create 解决，应进入 query 确认流程。
|
|
|
-13. 后端通过 `ChoosePayment=ALL` 与 `IgnorePayment=ATM#CVS#BarcodeATM` 保留信用卡和 Apple Pay；AFTEE 必须由 OMG 商户侧关闭，App 不得通过 CSS 或 DOM 注入修改第三方支付页面。
|
|
|
+13. App 只传 `CREDIT/APPLE_PAY`；不得传 `ChoosePayment`、`UnionPay`、`IgnorePayment` 等 OMG 原始字段，也不得通过 CSS 或 DOM 修改第三方支付页面。
|
|
|
14. 当前没有真实退款能力。
|
|
|
|
|
|
## 10. App 验收清单
|
|
|
@@ -659,12 +670,15 @@ token: <用户登录 token>
|
|
|
### 10.1 创建与收银台
|
|
|
|
|
|
- [ ] 创建订单时 OMG 使用 `payType = "2"`。
|
|
|
-- [ ] create 请求 Header 包含 token，JSON 只传 `orderId`。
|
|
|
+- [ ] App 只显示信用卡与 Apple Pay，并把选择映射为 `CREDIT/APPLE_PAY`；用户可见文案使用现有 i18n。
|
|
|
+- [ ] create 请求 Header 包含 token，JSON 只传 `orderId` 与 `paymentMethod`。
|
|
|
- [ ] 支付按钮有防重复点击处理。
|
|
|
- [ ] create 成功后，当前完整 WebView 使用 Form POST 打开 `gatewayUrl`。
|
|
|
- [ ] 所有 `formFields` 原样提交，`gatewayUrl` 不作为 input。
|
|
|
- [ ] 没有 iframe、GET 跳转或新窗口。
|
|
|
-- [ ] 测试收银台显示正确金额，信用卡可用，Apple Pay 在门店已开通且设备支持时可用，ATM/CVS/BarcodeATM 已隐藏，AFTEE 已在 OMG 商户侧关闭。
|
|
|
+- [ ] `CREDIT` 直接进入信用卡流程，表单为 `ChoosePayment=Credit + UnionPay=2`，不显示其他渠道。
|
|
|
+- [ ] `APPLE_PAY` 在门店已开通且设备支持时直接进入 Apple Pay 流程，表单为 `ChoosePayment=ApplePay`，不显示其他渠道。
|
|
|
+- [ ] 两种表单都不包含 `ChoosePayment=ALL` 或 `IgnorePayment`，页面不出现超商快付、AFTEE。
|
|
|
|
|
|
### 10.2 App 返回与状态确认
|
|
|
|
qmj