狀態、回呼與通知
狀態、回呼與通知
各欄位的責任
| 欄位 | 意義 |
|---|---|
status | Hosted 操作進度：created、in_progress、submitted、cancelled、expired |
merchant_kyc_status | 該商戶 KYC：draft、pending、under_review、approved、rejected，尚無申請時為 null |
identity_verified | 有效外站綁定所指身分已驗證；未完成綁定時為 false，不是平台全域 user 查詢 |
binding_status | 此外站帳號的身分綁定結果 |
membership_status | 該商戶會籍是否可用 |
eligibility | 已存在的後端決策快照及時間；沒有決策為 null，網站不得重算 |
member_ref 是 Client 專屬外站會員參照，不取代原 Partner Auth 的 sub。同 Merchant、同環境、同 verified identity 只容許一個有效外站帳號；identity_already_bound 應顯示人工處理入口，不覆寫綁定，也不能揭露另一帳號。
驗證完成且目前可用時，同時確認 binding_status=active、merchant_kyc_status=approved 與 available=true。商業或會籍停用會改變可用性，但不抹除歷史 identity_verified；各欄位分開呈現。遊戲權限仍由網站負責，本次玖天試接只提示及記錄。
Callback
Callback 只追加 session_id 與 state。網站後端必須比對發起交易保存的帳號、登入事件、session ID 及 state；使用常數時間比較 state，成功比對後消耗一次交易。若已登出或換帳號，要求登入原帳號，不把驗證結果綁到目前的其他會員。
無論 callback 帶什麼資料，結果都由 Server API 查詢。服務暫時不可用時顯示「同步中」並重試，不能把錯誤當成核准、退件或封鎖。
簽章 webhook
平台只送到預先登記的 HTTPS endpoint。請讀取原始 HTTP body，再驗證：
X-Ekyc-Timestamp: <Unix seconds>
X-Ekyc-Event-Id: <event UUID>
X-Ekyc-Key-Id: <登記的 signing key ID>
X-Ekyc-Signature: <lowercase hex HMAC-SHA256>
signature = HMAC-SHA256(signing_secret, timestamp + "." + raw_body)
使用專用 webhook signing secret，不是 Client secret。伺服器時間應同步；timestamp 與接收時間差超過 300 秒時拒絕。簽章使用常數時間比對，body 的 id 必須與 X-Ekyc-Event-Id 一致。
{
"id": "00000000-0000-4000-8000-000000000001",
"type": "verification.session.updated",
"version": 2,
"occurred_at": "2026-10-04T02:00:00+08:00",
"data": {
"member_ref": "00000000-0000-4000-8000-000000000002",
"session_id": "00000000-0000-4000-8000-000000000003",
"status": "submitted",
"identity_verified": true,
"merchant_kyc_status": "approved",
"binding_status": "active",
"membership_status": "active"
}
}
範例欄位由伺服器產生。事件不含證件、手機明文、影像或座標。請以 event ID 唯一鍵持久去重，並在同一交易內更新會員快照與最高 version；較舊版本不覆寫新狀態，重複事件回成功。Webhook version 與 Server API revision 是不同序列，不直接比較。
持久保存後才回 2xx；暫時無法保存時回 5xx。平台請求逾時 10 秒、退避重送最多 24 小時、不跟隨 3xx。接收端不要在 HTTP request 內執行長時間作業。通知遺失時仍可用 Server API 恢復狀態。