Changelog¶

本頁只記 PAYMENT 可見的契約異動：請求／回應欄位、callback／event、HTTP 狀態與錯誤碼。 Farm Server 版號與公開 tag vX.Y.Z 對齊。Admin、Android Device Agent、flows 腳本不在此列。

本站仍只維護目前有效的 API（沒有 /v2、沒有平行舊版）。各操作頁是現況；本頁回答「哪一版開始長這樣」。

沒有列出的版本 = 該次發版沒有改 Payment 的 HTTP／callback 契約。

[0.24.0] - 2026-08-28¶

Scheduler 建的 Balance 沒有單筆 callback_url，事件因此指名產生該次變化的已完成 task。

事件新增 source_task_id。
old／new／ts 只供提示，不是寫入依據。
PAYMENT 用自身 Bearer GET /v1/tasks/{source_task_id}，核對同裝置、type=balance、state=succeeded 後採用該次銀行讀值；不必另派 Balance probe。
事件離開 Farm 時該 source task 必定已終態且 result 完整。
過渡期：舊 Farm 事件沒有此欄，才 fallback 另派 probe。

POST /v1/tasks 的必填／選填欄位不變。以下由 Farm 寫入、不要由 PAYMENT 帶：

內部鍵	何時出現	PAYMENT 要做的事
`payload.ledger_reference`	`type=transfer_verify`：用 `not_before` 反查同裝置同租戶的原轉帳 `reference_number`	把原 transfer result 的 `not_before` 原樣帶入即可。對不到唯一原單就不寫該鍵，verify 無法強匹配（`ledger_verified` 不會是 `true`）
`payload.to_fullname_bank`	出款 VCB／BIDV 的 `transfer`／`transfer_verify` 查收款銀行對照表	繼續送 `to_bank` 簡碼。若多帶全名，Farm 會丟掉，只信自己的表。兩鍵都不進指紋、不進 GET／callback

Farmer 側新增 VN 收款銀行對照表（Admin／Web UI）。

Payment POST /v1/tasks、GET /v1/tasks/{id}、callback 契約不變。 請求仍送 to_bank 簡碼。

接口	契約
`POST /v1/enrollments` `bank_payload`	VN：`account_numbers` + `password`（必填）；`transfer_password`（OTP，可省）；禁止 `pin`（422）
`PUT /v1/devices/{device_code}/banks/{bank_code}/secret`	merge：可只改 `password` 或只改 `transfer_password`；省略鍵沿用；帶 `account_numbers` → 422
`GET /v1/devices`、`GET /v1/devices/{id}`	`banks[]` 增加非機密 `account_numbers`（未安裝為 `[]`）
`pin_configured`	VN = 密封袋有登入 `password`（寫入端；既有列不 backfill）
`POST /v1/tasks` `type=balance`	`payload.account_number` 可選；已有列表時必須是成員

請求驗證從「多餘鍵靜默吃掉」改成白名單 fail-closed：

bank_payload 未知鍵 → 422。允許鍵：VN account_numbers／password／transfer_password；GCash account_numbers／pin；TH iOS 只有 pin。
該 (device, bank) 尚無 secret 列時，enrollment 必須帶密（GCash 必填 pin，VN 必填帳號＋登入密）。舊版可先綁再 PUT 補密；GCash 這條路已關閉。
mode=bank_add 的 region 必須等於裝置 country_code。route 類失敗改為 404／409／422／503（不再一律 400）。
PUT secret extra="forbid"；至少一個密鍵，否則 422 secret update required（無法只改 variant）。
type=balance 開始驗 payload：型別／格式不符 → 422（整數 JSON 亦然）。
已安裝非空 account_numbers 且 payload 帳號非成員 → 422 account_number is not bound to this bank（新任務；冪等 replay 仍優先）。
綁多個 bank 卻未帶 bank_code → 入列前 400（舊版 202、由 worker 失敗）。單一綁定仍自動推導。

冪等鍵、transfer 禁止重送、transfer_verify、lock／unlock event、expected_locked_at 等仍以各現況頁為準；本 changelog 從越南憑證這輪開始記 Payment 可見異動。