{"openapi":"3.1.0","info":{"title":"SCGA Pay API","version":"2.0.0","description":"香港轉數快（FPS）／PayMe 收款核對 API。資金直接入商戶戶口，平台只做建單、核對、對賬。\n\n認證：所有商戶 endpoints 加 `X-API-Key: hkpay_...`。客戶端（付款頁、上載截圖）開放免 key。\n\n冪等：同一 `reference` 重複建立會回原有單。\n\nWebhook：事件以 HMAC-SHA256 簽名，header `X-HKPay-Signature: t=<ts>,v1=<hmac(ts.body)>`。"},"servers":[{"url":"https://api.pay.scga.hk","description":"生產"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer","description":"商戶後台 session token"}},"schemas":{"CreatePaymentRequest":{"type":"object","required":["amount_hkd","method","reference"],"properties":{"amount_hkd":{"type":"number","exclusiveMinimum":0,"example":200},"method":{"type":"string","enum":["fps","payme","both"],"default":"both","description":"both ＝同一張單同時出轉數快 QR 同 PayMe 連結（客人邊個方法唔通就轉另一個，付款碼同金額都一樣）。唔傳 = both；收款身份缺其中一樣會自動降級。","example":"both"},"reference":{"type":"string","description":"商戶單號，同一商戶內唯一","example":"BNI-KLN-2026-11-G37"},"description":{"type":"string","example":"嘉賓登記費"},"expires_in_minutes":{"type":"integer","example":1440},"payout_account_id":{"type":"string","format":"uuid"},"payout":{"type":"object","description":"inline 收款身份（需後台開啟 allow_inline_payout）","properties":{"fps_mobile":{"type":"string","example":"+85291111111"},"fps_id":{"type":"string"},"merchant_name":{"type":"string","description":"收款人全名（同銀行戶口一樣）。遮罩名／簡稱會被 422 拒絕，核對截圖要用。","example":"SZE CHI CHUNG GARY"},"payme_link":{"type":"string","example":"garysze77"}}}}},"Payment":{"type":"object","properties":{"payment_id":{"type":"string","example":"7bf929192a673bc0"},"reference":{"type":"string"},"method":{"type":"string"},"amount_hkd":{"type":"number"},"status":{"type":"string","enum":["pending","pending_review","paid","refunded","cancelled","expired"]},"payment_code":{"type":"string","description":"6 位付款碼，客人要喺轉數快備註／PayMe 訊息填","example":"792826"},"pay_payload":{"type":"object","properties":{"qr_data_url":{"type":"string","description":"data:image/png;base64,..."},"qr_text":{"type":"string","description":"EMVCo TLV payload"},"payme_url":{"type":"string"},"instructions":{"type":"string"}}},"payout":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true}}},"ProofResult":{"type":"object","properties":{"payment_id":{"type":"string"},"verified":{"type":"boolean"},"status":{"type":"string"},"amount_match":{"type":"boolean"},"reference_match":{"type":"boolean"},"reason":{"type":"string"},"note":{"type":"string"},"flags":{"type":"object"}}},"Error":{"type":"object","properties":{"detail":{"type":"string"}}}}},"paths":{"/health":{"get":{"summary":"健康檢查","security":[],"responses":{"200":{"description":"ok"}}}},"/api/v1/payments":{"post":{"summary":"建立收款單","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"201":{"description":"已建立","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"401":{"description":"API key 無效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"參數或收款身份有問題","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/payments/{id}":{"get":{"summary":"查收款單（免 key，付款頁用）","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"收款單","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"搵唔到"}}}},"/api/v1/payments/by-reference/{reference}":{"get":{"summary":"用商戶單號查","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"收款單"},"404":{"description":"搵唔到"}}}},"/api/v1/payments/{id}/proof":{"post":{"summary":"上載付款截圖 → AI 核對（免 key）","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"auto_confirm":{"type":"string","enum":["true","false"]}},"required":["file"]}}}},"responses":{"200":{"description":"核對結果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofResult"}}}},"413":{"description":"圖太大（>10MB）"},"415":{"description":"格式唔支援"},"429":{"description":"上載次數用盡"}}}},"/api/v1/payments/{id}/cancel":{"post":{"summary":"取消未付款單","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"已取消"},"400":{"description":"狀態唔准取消"}}}},"/api/v1/reconciliation":{"get":{"summary":"對賬（已扣退款）","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"對賬摘要 + 逐筆"}}}},"/api/v1/reconciliation.csv":{"get":{"summary":"對賬 CSV（Excel 開）","responses":{"200":{"description":"CSV"}}}},"/api/v1/payout-accounts":{"get":{"summary":"列出收款身份","responses":{"200":{"description":"列表"}}},"post":{"summary":"新增收款身份","responses":{"201":{"description":"已建立"}}}},"/api/v1/payout-accounts/{id}":{"patch":{"summary":"改收款身份（設預設／停用）","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"已更新"}}}}},"x-webhook-events":["payment.paid","payment.pending_review","payment.refunded","payment.cancelled","payment.expired","ping"]}