網站快速串接

Hosted Web KYC 讓會員在瀏覽器完成手機 OTP、證件與活體拍攝，不必先安裝 App。平台維護拍攝、續辦與審核頁，網站保留原本登入及業務規則。這是原 Early Access Core 之後的 v1 擴充，預設關閉；平台開通 Client 操作權限並提供隔離沙盒後才可串接。

準備

請向平台取得 HTTPS API 入口、Client ID、Client secret，並登記確切的回站網址。EKYC_API_BASE 為包含 /api/partner/v1 的完整入口。Client 必須歸屬一個 Merchant 及 production／sandbox 環境。正式與測試資料不得混用。

Secret 只放在網站後端。瀏覽器、JS、行動 App 及原始碼都不應包含它。操作權限為 verification.create、verification.read、verification.launch、login-locations.write；平台可只核發所需權限。

最短整合流程

1. 會員以網站原本的方式登入。
2. 網站後端以 session 內的會員 ID 作 external_user_ref，產生隨機 state 與 Idempotency-Key。
3. 後端呼叫 POST /api/partner/v1/verification-sessions，保存回傳的 session_id、member_ref 與原帳號／登入工作階段對應。
4. 瀏覽器導向 launch_url。該網址為 10 分鐘、單次票券，不寫入日誌或 analytics。
5. 會員送審後回到 allowlisted callback。後端確認原帳號仍登入且 state 相符，再查詢 GET /api/partner/v1/verification-sessions/{session_id}。
6. 待審案件以狀態查詢或已驗章 webhook 更新；query string 不代表核准。

# 下列變數由後端安全設定提供；不要將實際 secret 貼入終端紀錄。
curl --fail-with-body --request POST "$EKYC_API_BASE/verification-sessions" \
  --user "$EKYC_CLIENT_ID:$EKYC_CLIENT_SECRET" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $TRANSACTION_ID" \
  --data '{"external_user_ref":"example-member-123","return_url":"https://partner.example.invalid/ekyc/callback","state":"replace-with-a-random-server-side-state"}'

回應外層為 data，其中包含 session_id、member_ref、status、revision、expires_at、launch_url 及公開結果。不要依 launch_url 或 status=submitted 自行判斷核准。

續辦與既有會員

POST /verification-sessions/{session_id}/launch-links 核發新票券，請帶新的 return_url、state 與 Idempotency-Key。票券到期只需重開入口，不重建已送審案件。

同一外站會員的草稿可續辦；已核准的回訪會員不需要每次拍臉。退件後由會員明確啟動重送。不要以相同手機或 Email 合併帳號；跨商戶重用身分必須在 eKYC 登入既有帳號並明確同意。

桌機可選 QR 接續：手機先 OTP，桌機確認配對短碼及遮罩門號後才允許拍攝。QR 只接續該次驗證，不移轉網站登入權限。

開發者交付物

原始碼交付包含 docs/openapi/hosted-web-v1.yaml、examples/hosted-php73/ 的純 HTTP PHP 範例、webhook 驗章及 callback 比對。整合者只需使用公開 API，不需閱讀 Laravel／Flutter 內部程式。正式簡訊、真模型與手機實機另行驗收。