Farm PAYMENT API¶
Farm 是 PAYMENT 與實體銀行 App 之間的裝置與任務中介。本站只涵蓋 PAYMENT 接入面： Bearer API、callback／event contract、以及可依序照做的操作 FLOW。
範圍
不包含 Admin、FarmAgent loopback、WDA、RabbitMQ、DB、CLI 或內部部署文件。 範例一律使用 placeholder，不含真實 API key、PIN、帳號或 callback URL。
四個角色¶
| 角色 | 職責 |
|---|---|
| PAYMENT | 持有 tenant API key；建立 enrollment／task；接收 callback；以 GET 作恢復入口 |
| Farm Server | 鑑權、租戶隔離、入列、狀態權威、best-effort 或 outbox 通知 |
| FarmAgent / Field | 現場輸入 enrollment token，綁定實體手機（PAYMENT 不直接呼叫 redeem） |
| Bank App（裝置） | 透過 WDA 執行 balance／明細／轉帳；PAYMENT 不直接碰裝置 |
閱讀順序¶
- 五分鐘接入 — Base URL、Bearer、smoke test
- 裝置註冊與綁定 — 新機與既有機加銀行
- 裝置、PIN 與解鎖 — 查詢、PIN、解綁、解鎖 generation
- 任務與轉帳安全 — 四種 task 與 transfer 禁止重送閘門
- Callback 與事件 — 分流、冪等鍵、投遞保證
- 錯誤與重試 — 依「能不能重送」決策
- 正式接入檢查表
- 接口索引
命名：device_code 與 device_id¶
同一個值、兩個欄位名。 實體手機短碼（如 TH-XXXX）：
| 情境 | 用哪個 |
|---|---|
POST /v1/tasks 請求 |
device_code（preferred）；device_id 為 legacy alias |
POST /v1/tasks 回應 |
兩個都回，值相同 |
GET /v1/tasks/{id}、GET /v1/devices/{id} 回應 |
欄位名常為 device_id，值即 device_code |
新整合請一律送 device_code。
核心原則¶
Callback 是通知，GET 是恢復入口
Callback 多為 best-effort（task／bound／balance 無持久化重送）。
權威狀態永遠以 GET /v1/enrollments/{id}、GET /v1/tasks/{id}、
GET /v1/devices/{id} 為準。收到 callback 後應先冪等落地，再異步處理。
Transfer 禁止雙重出款
見 任務與轉帳安全 頁首決策表。
money_moved=true、needs_reconciliation=true、
interrupted_needs_reconciliation 時禁止用新 key 重送 transfer。
verification.deferred=true 時只送 transfer_verify，不重送出款。