正式接入檢查表

本表定義 PAYMENT 接入方應驗證的項目。不宣稱本文件撰寫時已實跑任一環境。

PRE

Auth 與租戶

• [ ] 正確 Bearer → 200（如 GET /v1/devices）
• [ ] 缺 Bearer → 401
• [ ] 錯誤 key → 401
• [ ] 他 tenant 的 device_id／task_id／enrollment_id → 404（不洩漏）

Enrollment

• [ ] device_create：不帶 device_code → 取得一次性 token 與新 device_code
• [ ] 現場 redeem 後收到或 GET 到 device.bound／state=bound
• [ ] bank_add：帶既有 device_code → bank.bound；GET device 見 pin_configured
• [ ] Token 只在 issue 回應出現一次；過期／重用行為符合預期
• [ ] Callback 遺失：僅靠 GET /v1/enrollments/{id} 可恢復

PIN／Lock

• [ ] PUT secret：6 位數字成功；非 6 位 → 422
• [ ] Response 不含明文 PIN
• [ ] DELETE bank → 204；再 DELETE → 404
• [ ] Unlock：正確 expected_locked_at → 200；過期 generation → 409
• [ ] Unlock 不改變 schedule_enabled（與 ops 約定驗證）

四種 task

• [ ] balance → 202 → terminal callback 或 GET
• [ ] transaction_pull daily／recovery
• [ ] transfer（必填 idempotency_key）
• [ ] transfer_verify（deferred 欄位原樣帶入）
• [ ] POST /v1/transaction-pull/recovery 等價 recovery task

冪等與超時

• [ ] 同 key 同 body → 200 replayed，task 為原單
• [ ] 同 key 不同 fingerprint → 409 conflict
• [ ] Submit timeout：同 key 重送或 GET by key，不對 transfer 換新 key
• [ ] 裝置已鎖時同 key 重送仍 replay（不被 423 遮蔽）

Callback

• [ ] 無 event → task terminal；有 event → 事件
• [ ] 快速 2xx + 冪等落地
• [ ] 模擬 duplicate callback 不重複入帳
• [ ] 模擬 loss：僅 GET 可對齊狀態
• [ ] 3xx 不被 Farm 跟隨（自家 handler 勿依賴 redirect）

Transfer 無雙重出款

• [ ] money_moved=true 路徑：整合層拒絕自動重送
• [ ] needs_reconciliation／interrupted_needs_reconciliation：進人工、不重出款
• [ ] verification.deferred=true：只發 transfer_verify
• [ ] Confirm 前失敗：才允許新 key 策略

Production

• [ ] OL Base URL／API key 來自 secret manager（非文件、非 git）
• [ ] Tenant callback_url 為正式 HTTPS 端點；origin 與 task 覆寫一致
• [ ] /ready 納入探針；/health 僅 liveness
• [ ] 重跑 PRE 檢查表上全部 money-path 與負向 auth 項
• [ ] 告警：callback 5xx、對帳佇列、lock 事件
• [ ] 文件站與 API 憑證分離；本站 Access allowlist 與 API key 無關

明確非目標（不要驗成「文件站功能」）

• 文件站內 Try it 或瀏覽器直打 Farm API
• 真實 PIN／帳號寫進文件或 CI log
• Admin／agent 路由出現在本站