身分驗證與 IP 白名單

檢查順序

每個請求依下列順序檢查，任一項不通過就回傳錯誤：

1. 簽章：api_identity 必須是狀態為正常的憑證，且 sign 正確。不通過回 invalid_signature（HTTP 401）。
2. 時間戳：timestamp 必填，格式 yyyy-MM-dd HH:mm:ss（UTC+8），與 ST Pay 伺服器時間相差不得超過 5 分鐘。缺少回 missing_parameter，格式不符回 invalid_parameter，相差超過 5 分鐘回 timestamp_expired（HTTP 400）。簽章通過才檢查時間戳，所以 timestamp 被竄改時回 invalid_signature。
3. 來源 IP：必須在該商戶的 API 白名單內。白名單是空的就全部拒絕。不通過回 ip_not_allowed（HTTP 403）。
4. 商戶狀態（只有建單會檢查）：商戶被停用時不能建單，回 merchant_disabled（HTTP 403）。停用期間仍可查單。

保管金鑰

• 金鑰只能放在您的伺服器端，不要放進網頁、App 或任何會發給終端使用者的程式。
• 金鑰外洩或遺失時，請立即聯繫 ST Pay 建立新憑證並停用舊憑證。

更換金鑰

同一商戶可以同時有多組狀態為正常的憑證，每組都可以用來呼叫 API。Callback 一律以最新建立且狀態為正常的那組金鑰簽章，因此建議依以下順序更換金鑰：

1. 先讓您的 Callback 驗章程式能同時接受兩把金鑰（新金鑰在第 2 步之後才拿得到，可先準備好設定位置）。
2. 請 ST Pay 建立新憑證，並把新金鑰加入 Callback 驗章。新憑證建立後，Callback 會立即改用新金鑰簽章；新金鑰加入驗章之前收到的 Callback 會驗章失敗，這些單請以查單確認結果，或請 ST Pay 重發。
3. 呼叫 API 改用新的 api_identity 與金鑰。
4. 確認沒有請求再使用舊憑證後，請 ST Pay 停用舊憑證，並從 Callback 驗章移除舊金鑰。