常見問題
用 Ctrl-F 搜尋你正在除錯的症狀。每則回答刻意保持精簡，並連結到包含完整說明的章節。
入門
我從哪裡取得 api_key？
你的客戶經理會在 onboarding 期間發放。你會收到兩把獨立的金鑰 — 一把給 sandbox（通常以 pre_ 為前綴），一把給正式環境。沒有自助式發放入口。請見 Security 了解儲存與輪替規則。
sandbox 與正式環境有什麼差別？
Sandbox（https://pre-api.open-pay.co）跑的是與正式環境（https://api.open-pay.co）相同的程式碼，但對應到隔離的資料庫、隔離的渠道與模擬資金。憑證、餘額與訂單不會在兩者之間互通。請見 Sandbox 取得完整比較。
我的 api_key 正確，為什麼請求還是回 401？
401 的成因可能是簽章錯誤或 X-Timestamp 超出時窗，而不是金鑰本身。檢查 JSON 信封中的 code 欄位：INVALID_SIGNATURE 與 INVALID_TIMESTAMP 都是 401。請見 Errors 取得驗證碼目錄。
我可以不用公開的 callback URL 測試整合嗎？
不行。Gateway 會透過 HTTPS 把回調送到它能連到的 URL。本地開發可以用 ngrok 通道、request-bin，或你自己基礎設施中僅 sandbox 用的主機。請見 Callbacks 了解你必須接受的請求形狀。
我怎麼知道我的帳號有哪些渠道可用？
渠道路由由營運方管理，不透過商戶 API 揭露。請向你的客戶經理詢問你的商戶在 sandbox 與正式環境分別串了哪些幣別與渠道。請見 Sandbox 了解為什麼 sandbox 的渠道覆蓋通常比正式環境少。
驗證與簽章
我的簽章一直失敗，要檢查什麼？
依序檢查：用 ASCII（不是 locale）排序 keys、跳過 null 值但包含空字串、串接 api_key 時不加 & 分隔符、輸出小寫 hex。Authentication 中的四份參考實作經 CI 逐位元組驗證 — 用範例對照你的輸出與它們的差異。
我的時間戳在 5 分鐘內，為什麼還是收到 INVALID_TIMESTAMP？
你的本機時鐘正在飄移。5 分鐘時窗是針對 gateway 的 NTP 同步時鐘判定，不是你的時鐘。執行 ntpdate（或你平台對應的指令）後重試。不要靠「相信伺服器回傳的時間戳」來「修正」飄移。請見 Security。
GET 請求也要簽章嗎？
要。簽章是針對查詢參數（若沒有任何參數則僅針對 timestamp=...）加上你的 api_key 計算。GET 範例見 Quickstart 第 4 步。
我可以改用 HMAC-SHA256 取代 MD5 嗎？
目前不行。簽章契約是 MD5(sorted_params + api_key)。未來若遷移到 HMAC-SHA256 會在 changelog 公告並提供並行接受期。不要預先實作。請見 Security 了解理由。
我要如何輪替 api_key？
聯絡你的客戶經理。營運方會發放第二把有效金鑰，你完成切換後，舊金鑰會在短暫重疊期（約 5 分鐘）後退役。沒有商戶入口的自助輪替。請見 Security。
充值與提款
Direct API 與 Cashier session 有什麼差別？
Direct API（POST /deposit）會立刻建立 DepositOrder，並回傳銀行資訊或 payment_url 讓你渲染。Cashier session（POST /deposit/cashier）會建立 CashierSession 並回傳 cashier_url；不帶 amount 時，DepositOrder 會在付款人於託管頁面提交時建立；帶 amount 時會立即建立 DepositOrder 並跳過面額選擇。請見 Deposits。
status MATCHED 何時會轉成 COMPLETED？
MATCHED 代表 gateway 已辨識付款；COMPLETED 代表帳本已把資金落帳到你的餘額。轉換通常在毫秒等級，但不保證即時。簽章回調是在 COMPLETED 觸發，不是 MATCHED。請見 Deposits。
為什麼我的提款卡在 PENDING？
提款上的 PENDING 代表必須由營運人員手動核准才能繼續前進。這由審核引擎驅動 — 訂單金額、單日筆數、白名單匹配都會影響。請見 Withdrawals 了解審核規則。
我可以透過商戶 API 取消提款嗎？
不行。沒有商戶取消端點。CANCELLED 只能透過營運方在內部 TransferTask 取消才能達到。若你誤送，請聯絡平台營運。請見 Withdrawals。
若付款人在我的充值單到期前未完成會發生什麼事？
訂單會轉成 EXPIRED 並停止接受付款。在到期後抵達的資金不會自動匹配，可能需要人工對帳。預設到期不會觸發回調 — 透過 GET /query/deposit/{order_no} 對帳。請見 Deposits。
回調
為什麼我會收到同一個回調兩次？
Gateway 會對任何未收到 2xx ack 的回調重試，最多 5 次、每次間隔 30 秒。合法重試期間的網路 race 與惡意重放在外觀上無法區分。請以 (order_no, status) 去重並以 200 ack。請見 Callbacks。
我的 callback_url 曾回 500 一次，gateway 會重試嗎？
會。5xx、逾時與網路錯誤都會觸發重試。排程固定為 30s、30s、30s、30s — 總共五次嘗試、橫跨約 2 分鐘 — 之後轉 FAILED。請見 Callbacks 了解重試語意。
回調最久會重試多久？
5 次嘗試之後（距首次送出約 2 分鐘）NotificationLog 會標記為 FAILED，不再嘗試。若你的端點整個時窗都掛掉，5 次都會失敗，你必須透過 /query/* 端點對帳。請見 Callbacks。
回調可能不按順序抵達嗎？
可能。在故障恢復期間，deposit.matched 可能在 deposit.completed 之後才抵達。你的 (order_no, status) 冪等表會避免狀態重複套用，但你的業務邏輯必須能接受終態，無論中間態以什麼順序先到。請見 Callbacks。
ack 回應需要回傳 body 嗎？
不需要。任何 2xx 都視為成功 ack；body 會被忽略。包含 success 一詞的 body 也接受。請快速回應 — 每次嘗試的逾時是 10 秒。請見 Callbacks。
錯誤與重試
我收到 5xx，應該重試嗎？
要重試，使用指數退避，並用相同的 merchant_order_no。建立類呼叫上的 5xx 不代表訂單沒建立 — 伺服器可能在失敗前已 commit。重試後用 merchant_order_no 查詢確認真實狀態。請見 Errors。
OPTIMISTIC_LOCK_ERROR 是什麼意思？
並發更新在同一筆商戶餘額或訂單列上與你的請求競爭到。這是暫態的。用短 jitter 最多重試 3 次，再查詢訂單確認首次嘗試是否已落地，再決定是否重送。請見 Errors 與 Withdrawals 了解重試模式。
為什麼重複的 merchant_order_no 會回 409？
重複的 merchant_order_no 現在會以 HTTP 409 回傳，並在標準 {success, code, message, data} 錯誤信封中帶上 CONFLICT code。不要盲目重試；請先用 merchant_order_no 查詢既有訂單，再決定下一步。請見 Deposits 與 Errors。
我可以依賴 message 文字做錯誤處理嗎？
不可以。message 欄位不屬於 API 契約 — 措辭可能毫無預警地變動。請永遠以信封中的 code 欄位做分支。請見 Errors。
Sandbox 與營運
我的 IP 應該在允許清單上，為什麼連不上 / 收到 403？
來源 IP 只在 Cloudflare 邊緣（WAF / Access）這一層統一管控，應用層不再做任何來源 IP 檢查。若你的 IP 沒被邊緣放行，症狀會是 TLS 握手失敗或拿到 Cloudflare 的 HTML 挑戰／封鎖頁，而不是 JSON 403 信封。請向你的客戶經理確認你的 IP 已加入 Cloudflare Access 允許清單。若你收到的是 JSON 403 AUTHORIZATION_ERROR 信封，那代表商戶被停用或缺少 can_deposit / can_withdraw 權限，與來源 IP 無關。請見 Sandbox。
我要怎麼在 sandbox 重現特定渠道失敗？
Sandbox 渠道可由營運團隊調整，回傳特定狀態（PENDING、COMPLETED、FAILED）以供測試。請你的客戶經理把你的 sandbox 商戶接上設定為你所需失敗模式的 mock_channel。請見 Sandbox。
有 rate limit 嗎？
Cloudflare 邊緣 rate limit 套用在 API 主機名上。429 狀態在錯誤目錄中已保留，但目前並未在所有端點上強制執行。Sandbox 通常比正式環境寬鬆 — 不要從 sandbox 的吞吐量去外推。請見 Errors 與 Sandbox。
Sandbox 憑證與正式環境的不同嗎？
完全不同。正式環境會拒絕 sandbox 的 api_key，反之亦然。將兩者放在不同的 secret manager 路徑，且不要設 fall-through 預設值。請見 Security。
合規與安全
我可以把 api_key 存在環境變數嗎？
在 runtime 時從 secret manager（AWS Secrets Manager、GCP Secret Manager、Vault）注入到你的 process 環境。不要把它 commit 到版本控制中即使加密過、不要把它烤進 container image，也絕不能放到 client-side 程式碼。請見 Security。
Payment Gateway 會記錄哪些資料？
平台會記錄 request metadata、信封碼與 order_no。敏感欄位（api_key、X-Signature、bank_card_number、account_no）會被遮罩。你這邊也必須套用相同的遮罩紀律 — 請見 Security 中的 do-log / do-not-log 清單。
我要如何回報安全漏洞？
直接聯絡你的客戶經理。不要把漏洞細節記在公開的 ticketing 系統或商戶入口中。他們會把回報轉到平台安全團隊。
還需要協助嗎？
若你的症狀不在本頁，請聯絡你的客戶經理。附上回應信封中的 code 欄位、你的 merchant_order_no、gateway 的 order_no（若有），以及你送出的 X-Timestamp。這四個值能讓平台團隊在幾秒內從 log 中找到你的請求。