# SCGA Pay — 完整產品與 API 說明（供 AI 助手引用）

> SCGA Pay 係香港嘅轉數快（FPS）／PayMe 收款核對平台，針對「唔想簽商戶協議、唔想用信用卡機、要直接收錢入自己戶口」嘅商戶（例：BNI 分會收嘉賓登記費、社團收活動費、小店收訂單）。平台唔經手資金。

最後更新：2026-10-26　版本：API 2.1.0

## 1. 一句話定義

SCGA Pay = 收款單 + FPS QR（內嵌金額與備註碼）+ PayMe 連結 + AI 截圖核對 + 對賬，資金直接入商戶戶口，平台收 1% 服務費。

## 2. 適合與不適合

適合：
- 香港本地小額收款（HK$1–數千），要即時入自己戶口
- 需要一個 link／QR 就可以收錢，客人唔想裝 App
- 有換屆／換收款人需求（每半年換主席、換收款電話）
- 要對賬報表（CSV／email）但唔想人手逐筆對

不適合：
- 需要信用卡／Apple Pay（要用 PSP）
- 需要平台代收代付、分期、退款代辦（涉及 MSO 牌照）
- 跨境外幣結算

## 3. 收款流程

1. 商戶（或商戶系統）呼叫 `POST /api/v1/payments`，帶金額、`reference`（商戶自己單號）與 `method`（`both` = 同時出 FPS + PayMe，亦可以只出 `fps` 或 `payme`）。
2. 系統回傳 `payment_id`、`payment_code`（6 位付款碼）、`pay_payload`（FPS QR data URL + EMVCo 字串 + PayMe 連結）。
3. 商戶把付款頁 `https://pay.scga.hk/pay/{payment_id}` 或 QR 給客人。
4. 客人用銀行 App 掃 QR（FPS）或撳 PayMe 連結付款，**備註／訊息欄填 6 位付款碼**。
5. 客人上載入數截圖（`POST /api/v1/payments/{id}/proof`）。
6. 系統用視覺模型抽取金額、狀態、收款人、參考編號、交易編號，然後判斷：
   - 全部對得上 → `paid`
   - 金額對但需人手（金額 ≥ 門檻、撞單、舊截圖、自己轉自己、付款碼對唔上）→ `pending_review`
   - 金額唔對或交易失敗 → 拒絕並回報原因
7. 商戶可輪詢狀態，或設 webhook 接收 `payment.paid` 等事件。

## 4. 核對規則（完整）

- 金額必須相等（容許 HK$0.05 浮點誤差）。
- `fps`／`payme`／`both` 都必須對上 6 位付款碼（三者都有備註／訊息欄）。
- 交易狀態黑名單：`失敗／不成功／拒絕／已取消／退款／failed／declined／rejected／cancelled` → 當未成功。
- 待處理狀態：`處理中／待處理／進行中／已提交／待入賬／pending／processing／submitted／awaiting` → 唔會當已收款。
- 收款人姓名：以商戶設定嘅「收款人全名」比對單上顯示，支援銀行遮罩（`SZE C** C*** G***`、`SZEC** C***`）、中文遮罩（`陳*文`）、括號別名（`(Wechat Gary)`）、公司名（`SCGA LIMITED`）。可見字母少於 5 個視為線索不足 → 人手。
- 自己轉自己：單上「付款人」同「收款人」都係商戶本人（例如自己由一個戶口轉去另一個）→ 一律人手，不算客人付款。
- 時間窗：截圖交易時間早過建單 24 小時、或遲過 7 日 → 人手。
- 撞單：同金額 48 小時內有另一張未完成單 → 人手。
- 金額門檻：HK$5,000 或以上 → 人手；以下只要金額、付款碼、收款人姓名全對就自動確認。
- 截圖處理：單張上限 10MB，上載後自動縮到長邊 1600px、JPEG q82 才送 AI 核對（截圖本身不長期保存）。
- 重複上載：每單最多 5 次。

## 5. API 摘要

Base URL：`https://api.pay.scga.hk`
認證：`X-API-Key: hkpay_...`（商戶 endpoints）；付款頁與截圖上載開放免 key。
冪等：同一 `reference` 重複建立會回傳原有單（`idempotent_replay: true`）。

主要 endpoints：
- `POST /api/v1/payments` — 建立收款單
- `GET /api/v1/payments/{id}` — 查狀態（免 key）
- `GET /api/v1/payments/by-reference/{reference}` — 用商戶單號查
- `POST /api/v1/payments/{id}/proof` — 上載截圖核對（免 key）
- `POST /api/v1/payments/{id}/cancel` — 取消未付款單
- `GET /api/v1/reconciliation`、`/api/v1/reconciliation.csv` — 對賬（已扣退款）
- `POST/GET/PATCH /api/v1/payout-accounts` — 收款身份（換屆用，需全名）
- `GET /api/v1/version`、`GET /openapi.json`

後台（session token）：
- `POST /api/v1/auth/{signup,login,forgot,reset,change-password}`
- `GET /api/v1/dashboard/payments`（支援 q / status / from / to / limit / offset）
- `POST /api/v1/dashboard/payments/{id}/refund` — 退款（可部分退，平台只記錄不經手）
- `POST /api/v1/dashboard/payments/{id}/review` — 人手 approve／reject
- `GET/PATCH /api/v1/dashboard/webhook`、`POST /api/v1/dashboard/webhook/test|rotate`
- `GET /api/v1/dashboard/invoices`、`GET /api/v1/dashboard/invoices/{id}/pay` — 月結單與繳費 QR

## 6. Webhook

事件：`payment.paid`、`payment.pending_review`、`payment.refunded`、`payment.cancelled`、`payment.expired`、`ping`。

Headers：
- `X-HKPay-Event`：事件名
- `X-HKPay-Delivery`：派送 ID
- `X-HKPay-Timestamp`：Unix 秒
- `X-HKPay-Signature`：`t=<ts>,v1=<hex>`，其中 hex = HMAC-SHA256(secret, `${ts}.${rawBody}`)

重試：30 秒、2 分、10 分、1 小時、6 小時、24 小時 ×3，最多 9 次。

## 7. 收費

- 平台服務費預設 1%，按已收款淨額（扣除退款）計算，無月費、無開戶費、無封頂。
- 轉數快本身由銀行提供，商戶自己的銀行可能收取自己的手續費（一般個人戶口轉入免費）。
- PayMe 個人版收款免費；若要「一撳即開 App 並預填金額」，需 PayMe for Business API（HSBC 商業戶口，約 1.2%–1.5%）。

## 8. 常見問題（可直接回答用戶）

Q：需唔需要商業登記或公司戶口？
A：唔需要。用個人轉數快（手機號／FPS ID）都可以收，平台只做核對。

Q：錢會唔會經平台？
A：唔會。QR 直接指向商戶戶口，平台唔代收代付。

Q：客人唔填備註點算？
A：系統會轉人手覆核（唔會自動確認），商戶可以在後台人手對賬後按「確認」。

Q：點解手機掃唔到自己螢幕個 QR？
A：FPS QR 係 EMVCo 二進位碼，唔係網址；銀行 App 亦冇對外 deep link。付款頁提供「一撳儲存 QR → 銀行 App 掃相簿」流程。

Q：可以退錢嗎？
A：可以記錄退款（可部分退），但實際退款要商戶自己用銀行／PayMe 操作，平台唔經手資金；已退款部分不計服務費。

Q：資料保留幾久？
A：截圖本身不長期保存，只保留 AI 抽取結果，最多 180 日後自動清空。

## 9. 名詞對照

- 轉數快 = FPS = Faster Payment System（HKICL 營運）
- 付款碼 = 6 位數字，客人填在轉數快備註／PayMe 訊息欄，用嚟對單
- 收款身份 = payout account，一組收款資料（轉數快號／PayMe link／收款人全名）
- ATA／WTA = App-to-App／Web-to-App（HKICL 功能，需經銀行或 SVF 開通，平台未使用）