foodie-server/specs/016-omg-payment/contracts/api.md

Contracts: OMG（歐買尬/FunPoint）AIO 支付接入

Feature: specs/016-omg-payment/spec.md Date: 2026-07-29

约束：OMG 全部独立实现，零 newebpay 依赖（见 research.md §0）。签名统一用 CheckMacValue(SHA256, EncryptType=1)，无 AES、无解密。

---

A. OMG 外部接口（我方 → 盘合）

A1. 幕前下单 — Cashier/AioCheckOut/V5（US1）

• URL：测试 https://payment-stage.funpoint.com.tw/Cashier/AioCheckOut/V5；正式 https://payment.funpoint.com.tw/Cashier/AioCheckOut/V5
• Method/CT：POST，application/x-www-form-urlencoded
• 方式：后端组参 + 计算 CheckMacValue 返回 form 字段，前端 Form Post 跳转 OMG 收银台（不可 iframe；iOS 不可另开窗）
• 必填请求参数：MerchantID、MerchantTradeNo(=OMG+ddId)、MerchantTradeDate(yyyy/MM/dd HH:mm:ss)、PaymentType=aio、TotalAmount(整数元)、ReturnURL、ChoosePayment=ALL、CheckMacValue、EncryptType=1
• 常用可选：TradeDesc、ItemName(# 分隔)、OrderResultURL、PaymentInfoURL、ClientRedirectURL、NeedExtraPaidInfo(建议 Y，供退款查 gwsr)、CustomField1–4、Language
• 固定：InvoiceMark=N（发票走 ezPay）；ReturnURL ≠ OrderResultURL；MerchantTradeNo 全平台唯一

A2. 付款结果回调 — ReturnURL（盘合 → 我方，US2）

• 盘合服务端 POST 我方 /pay/omg/notify（CT text/html）
• 参数：MerchantID、MerchantTradeNo、StoreID、RtnCode(1=成功，其余勿发货)、RtnMsg、TradeNo(OMG 交易号，须存并与 MerchantTradeNo 关联)、TradeAmt、PaymentDate、PaymentType、TradeDate、SimulatePaid(1=模拟，勿发货)、CustomField1–4、CheckMacValue
• 我方响应：纯字符串 1|OK（首字符 1=成功）；未收到 5–15 分重试，当天最多 4 次
• 核销校验顺序：CheckMacValue 验签 → RtnCode==1 → SimulatePaid!=1 → TradeAmt==订单 amount → trade_no 幂等

A3. ATM/超商 取号回调 — PaymentInfoURL（US3）

• 盘合服务端 POST 我方 /pay/omg/paymentInfo，返回虚帐/缴费码（BankCode/vAccount/ExpireDate 或 PaymentNo/ExpireDate 等，详见文档 02 页），带 CheckMacValue 需验签
• 我方落库展示并回 1|OK

A4. 订单查询 — Cashier/QueryTradeInfo/V5（凭证验证 / 补单）

• URL：测试 https://payment-stage.funpoint.com.tw/Cashier/QueryTradeInfo/V5；正式 https://payment.funpoint.com.tw/Cashier/QueryTradeInfo/V5
• 请求：MerchantID、MerchantTradeNo、TimeStamp(3 分钟内)、PlatformID?、CheckMacValue
• 响应(text/html，k=v)：TradeStatus(0 未付/1 已付/10200095 失败)、TradeNo、TradeAmt、PaymentDate、PaymentType、TradeDate、CheckMacValue…
• 用途：录入凭证探测金钥 + 回调漏收时补单

A5. 信用卡退款/取消 — CreditDetail/DoAction（US4）

• URL：正式 https://payment.funpoint.com.tw/CreditDetail/DoAction（stage 不可用）
• 请求：MerchantID、MerchantTradeNo、TradeNo、Action(C 關帳/R 退刷/E 取消/N 放棄)、TotalAmount、CheckMacValue、PlatformID?
• 响应(k=v)：RtnCode(1=成功)、RtnMsg
• 规则：已關帳→R、已授權→N、要關帳→E 再 N 或 R；分期必须全额；ATM/CVS/BarcodeATM 不适用（走人工）；自动关帳开启时避开 20:15–20:30

---

B. 平台内部接口（暴露给前端/管理端）

B1. 发起 OMG 支付 — POST /pay/omg/create（US1，@Anonymous @Auth，Header token）

• 入参：orderid（= ddId）
• 逻辑：校验订单归属/金额/未支付 → 查门店启用凭证 → 生成 MerchantTradeNo → 组参 + CheckMacValue → 落 pos_order_omg_payment(pay_status=0) + 更新 pos_order.pay_type="7"/pay_url
• 返回：form 字段 { gatewayUrl, MerchantID, MerchantTradeNo, MerchantTradeDate, PaymentType=aio, TotalAmount, ReturnURL, ChoosePayment=ALL, EncryptType=1, ItemName, CheckMacValue, ... }，前端构建隐藏 form 自动 submit 到 gatewayUrl

B2. OMG 支付结果回调 — POST /pay/omg/notify（US2，@Anonymous）

• 处理 A2：collectForm → IpnLog → 凭证(MerchantID) → 验签 CheckMacValue → 幂等(trade_no) → 金额校验 → RtnCode==1 && SimulatePaid!=1 → markSuccess → 更新订单(state=0, payStatus=1) + 订单日志 + 推送用户/商家/骑手 + sendAcceptRiderPush → 回纯串 1|OK

B3. 支付完成返回页 — GET|POST /pay/omg/return（US2，@Anonymous）

• 仅引导回前端结果页（带 ddId），不改订单状态（以 notify 为准）

B4. ATM/超商 取号回调 — POST /pay/omg/paymentInfo（US3，@Anonymous）

• 处理 A3：验签 → 落虚帐/缴费码 + 期限 → 回 1|OK

B5. 订单查询/补单 — POST /pay/omg/query（US2 补单，可选）

• 入参 orderid → 调 A4 → 据 TradeStatus 补单/查状态

B6. 订单取消退款（US4）

• 触发点：订单取消链路（PosOrderShOprate 商家取消 / UserOrderController 用户取消）内，对 OMG 已支付订单调 A5 DoAction；或 POST /pay/omg/refund?orderid=（落点 tasks 定）
• 写 pos_order_omg_refund；成功置 pos_order_omg_payment.pay_status=3、pos_order.pay_status=2

B7. 门店 OMG 凭证管理 — /system/storeOmg/*（US5，@PreAuthorize）

• GET /list（分页筛选）、GET /{storeId}、PUT /apply/{storeId}、PUT /saveCredentials（录入+QueryTradeInfo 探测验证）、PUT /toggleEnable/{storeId}、PUT /reset/{storeId}、PUT /enabledPayments/{storeId}
• 镜像 011 PosStoreNewebpayController 模式，但独立 Controller/Service/实体/表

---

C. 代码表与枚举（OMG reference 02–05，2026-07-29 补读）

C1. ChoosePayment（请求参数，US1）

本期固定 ALL（聚合全部）。可细分值：Credit（信用卡/銀聯/Apple Pay）、ATM（FIRST/CHINATRUST/UBOT/KGI）、CVS（CVS/FAMILY/IBON/HILIFE）、BarcodeATM（CHINATRUST）、AFTEE。 ⚠️ Apple Pay 不是独立 ChoosePayment，归在 Credit 下（付款页内选）；回覆 PaymentType 同为 Credit_CreditCard，仅凭 PaymentType 无法区分信用卡与 Apple Pay（本期不区分）。

C2. 回覆 PaymentType（回调 PaymentType，落 pos_order_omg_payment.pay_type）

PaymentType	名称	即时/延期
Credit_CreditCard	信用卡（含銀聯/Apple Pay）	即时
BarcodeATM_CHINATRUST	超商快付代碼繳費	即时
ATM_FIRST / ATM_CHINATRUST / ATM_UBOT / ATM_KGI	各银行 ATM	延期（取虚帐→期限内付款）
CVS_CVS / CVS_FAMILY / CVS_IBON / CVS_HILIFE	超商代碼繳費	延期
AFTEE_AFTEE	AFTEE 先享後付	延期

延期方式（ATM/CVS/AFTEE）走 PaymentInfoURL 取号 → US3。

C3. RtnCode（回调 / 退款响应）

1 = 成功；其余均为失败。完整代码表文档为图片且持续新增，须到「歐買尬廠商後台 → 系統開發管理 → 交易狀態代碼查詢」查全。 实现策略：RtnCode==1 视成功（核销 / 退款成功）；非 1 一律失败，记录 rtn_code+rtn_msg 供诊断，不硬编码错误码分支。

C4. URLEncode（CheckMacValue 计算，须完全照此 · reference 05）

.NET 风格 URLEncode。Java 实现：URLEncoder.encode(s, UTF_8)（空格已→+）后，照 PHP 范例做替换以对齐 .NET，再转小写、SHA256、hex 大写：

• 不编码（字面）：- _ . ! * ( )；~→%7e（两侧同）。
• 空格→+（.NET/Java 表单编码一致；标准 URLEncode 是 %20，勿混用）。
• 其余特殊符 @ # $ % ^ & = + ; ? / \ > < [ ] { } : ' " , | 均为 %XX；中文按 UTF-8 %XX。
• 替换集（防御性，照 PHP 范例）：%2d→-、%5f→_、%2e→.、%21→!、%2a→*、%28→(、%29→)（Java URLEncoder 本就不编 -_.，!*() 需替换回）。

签名约定（所有请求/回调通用）

CheckMacValue(EncryptType=1, SHA256)： 去 CheckMacValue → 参数按 key 字母序 → k=v&... → 包夹 HashKey={k}&..&HashIV={iv} → .NET 风格 URL 编码(-_.!*() 不编码) → 转小写 → SHA256 → hex 大写。校验同理重算比对。实现：OmgCheckMacValue（独立，不复用 NewebPayEncryptUtil）。