更新日誌

所有破壞性變更（刪欄位、改語義、改型別）都會升 major 版本並提前公告。新增欄位是非破壞性變更。

v1.4（當前）

新增

• 2026-09-08：首充最低金額與免手續費底額拆分。 /card_configs/list 新增 min_first_deposit、/card/first_deposit/preview 新增 min_first_deposit_amount：生效的首充總額最低值（max(initial_deposit / base_amount, 套餐或卡頭設定的首充最低)，含底額）。initial_deposit / base_amount 語義不變（1:1 免手續費的部分）。非破壞性新增欄位；未設定首充最低的套餐該值等於底額。
• 2026-08-21：新增支援的 card_type 取值 virtual_a（虛擬卡 A 類，與 V / R / G 同一提供方體系）。所有既有端點均可用 —— 列卡頭 / 列卡配置 / 首充預覽 / 申請虛擬卡 / 充值 / 卡詳情（含敏感欄位）/ 凍結 / 解凍 / 銷卡 / 交易明細 —— 所有出站 webhook（card.opened、card.open_failed、card.recharged、card.recharge_failed、card.closed、card.status_changed）同樣覆蓋。協議級開卡規則見 A 卡特殊約束：email 始終必填，不收手機號（phone* / use_bound_phone 被忽略），first_name + last_name 必填且不能為空白；違反時在凍結任何資金之前返回 400 virtual_a_required_fields_missing。非破壞性變更 —— 無新端點、無結構變化；按 card_type 分支的客戶端需補充新取值。
• 2026-08-21：/card_headers/list 與 /card_configs/list 新增響應欄位 kyc_requirement（開卡平台實名要求：require_kyc / kyc_type / kyc_level）。套餐行內為有效值（卡頭 > 卡配置 > 卡類型三級合併，即 apply 實際校驗口徑），卡頭行內為未選套餐時的預覽。require_kyc=true 且終端帳號未達標時 /card/apply 返回 400 kyc_required。非破壞性新增欄位；欄位結構見卡頭列表文件。

變更

• 2026-09-08：/card/apply 開始強制套餐首充最低金額。 first_deposit_amount 必須 ≥ min_first_deposit；套餐把首充最低設得高於底額時該欄位變為必填 —— 不傳 / 留空（仍預設底額）會被 400 first_recharge_below_min 拒絕（預覽以 invalid_reason 同樣回報）。未設定首充最低的套餐行為與之前完全一致。請從列卡配置讀取 min_first_deposit（或預覽的 min_first_deposit_amount）並始終顯式傳 first_deposit_amount。
• 2026-08-21：客戶經理管控卡頭改為按賬號過濾。 平臺交給客戶經理管控（由經理按客戶放開）的卡頭，/card_headers/list 僅在您的賬號已繫結有效客戶經理、且該經理已對您放開時才返回（對單個賬號的設定優先於經理統一設定）；否則服務端過濾、不計入 total —— 此前會照常列出、到開卡才被拒。/card_configs/list、/card/first_deposit/preview 現在提前做同一校驗，返回 400 account_manager_bind_required / account_manager_unavailable / account_manager_open_disabled（與 /card/apply 既有錯誤碼一致）。/card_configs/list 同時不再返回客戶經理已對該賬號關閉的套餐。存量卡不受影響。對於從列表介面動態獲取 header_id / package_id 的對接方為非破壞性變更；硬編碼了卡頭 ID 的對接方建議重新整理。詳見錯誤碼。
• 2026-08-21：/card_headers/list 的 require_email / require_phone 改為生效值。 解析口徑與開卡校驗完全一致（卡型別預設 → 卡頭覆蓋 → 協議規則：virtual_g 兩者必填、virtual_a 郵箱必填且不收手機號、virtual_v 兩者可選），且不再為 null。此前僅透傳卡頭原始配置，可能與開卡校驗不一致。非破壞性（欄位名與型別不變）。
• 2026-08-21：/card/apply 上帶上下文包裝的業務錯誤改為以 400 + message_key 返回。 virtual_a_required_fields_missing、virtual_g_name_invalid 這類校驗失敗此前會被誤歸類為 500 openapi_apply_card_failed，現在返回 400 + 文件中的 key。已把 4xx key 當作終態處理的對接方無需改動。
• 2026-08-21：/card_headers/list 不再返回非虛擬卡卡頭。 「僅虛擬卡」過濾下推到查詢層（不計入 total）；此前平台若配置了實體卡等非虛擬卡卡頭會被照常列出，拿去 /card_configs/list / /card/apply 才返回 400 openapi_card_type_not_supported。對只消費虛擬卡卡頭的對接方無感知。

v1.3

新增

• 2026-08-03：敏感卡資訊支援使用者二次驗證自助獲取。/card/info 傳 with_sensitive=true 不再要求管理員為憑證開通許可權：隨請求提交賬戶的交易認證憑據（email_code / pin / two_fa_code / sms_code）即可 —— 與 Web 端檢視 CVV 完全同一套驗證流程（驗證碼一次性、10 分鐘有效、防爆破鎖定）。配套新端點：
  • POST /api/v1/openapi/card/sensitive/send_code —— 傳送郵箱/簡訊驗證碼並告知需要哪些驗證因子（用途固定，同一賬戶 60 秒冷卻，帶 Retry-After）。
• 2026-08-03：銷卡端點正式收錄。POST /api/v1/openapi/card/close —— 不可撤銷地註銷虛擬卡（非同步：受理後 closing(4)，完成以 card.closed webhook 為準；餘額經平臺稽核後退回錢包）。該端點 v1.2 起已上線但此前未收錄文件（preview 狀態）；v1.3 正式納入對外契約，行為無變化。
• 2026-08-03：信任視窗（驗證一次，視窗內免驗證）。二次驗證成功後，同一賬戶在管理員配置的時長內（預設 30 分鐘，0=關閉，固定視窗不滑動）再次獲取敏感資訊無需任何驗證欄位。send_code 新增響應欄位 grace_active，用於探測當前是否需要驗證碼。非破壞性變更 —— grace_active 為新增欄位。

變更

• 管理員開通的敏感訪問權語義變為免二次驗證特權（面向無人值守 server-to-server 自動化；仍預設關閉、仍需審批）。已開通的憑證行為無任何變化 —— with_sensitive=true 繼續免驗證碼使用。
• 管理員封禁：平臺可按卡或按賬戶維度強制關閉敏感資訊獲取。封禁同時壓制兩條授權路徑（驗證碼與免驗證特權憑證均無效），返回 403 card_sensitive_access_banned；賬戶維度封禁同時攔截 /card/sensitive/send_code。
• /card/info 不再返回 403 openapi_sensitive_card_info_disabled。未開通特權的憑證傳 with_sensitive=true 但缺驗證碼時，現在返回 403 + 具體缺失因子的 key（email_code_required / pin_required / 2fa_code_required / sms_code_required）；驗證失敗/鎖定時返回 403 invalid_* / 429。此前匹配 openapi_sensitive_card_info_disabled 的對接方請改為匹配上述 key —— 詳見錯誤碼。

v1.2

新增

• 2026-07-07：新增卡片凍結 / 解凍與交易明細端點（4 個）。非破壞性變更——不改動任何已有端點。
  • POST /api/v1/openapi/transactions/list —— 查詢名下所有虛擬卡的交易明細
  • POST /api/v1/openapi/card/transactions/list —— 查詢單張卡的交易明細
  • POST /api/v1/openapi/card/freeze —— 凍結一張活躍虛擬卡
  • POST /api/v1/openapi/card/unfreeze —— 解凍使用者主動凍結的卡
• 交易物件嚴格脫敏：僅返回 last_four（絕不返回完整 PAN），不含持卡人 PII，不含供應商側 / 內部訂單引用。
• 凍結 / 解凍無需 Idempotency-Key——不涉及資金變動，且被卡狀態機保護（重複凍結 → card_already_frozen；重複解凍 → card_not_frozen）。僅使用者主動凍結可透過 /card/unfreeze 解凍；風控 / 管理員 / 系統凍結返回 403。

v1.1

新增

• 2026-06-15：/card/apply 透過可選的 first_deposit_amount 支援自定義首充金額，並新增只讀的 /card/first_deposit/preview 試算端點。非破壞性變更——first_deposit_amount 可選（空 = 配置底額）；預覽是新增端點，不改動任何已有端點。
• 2026-05-26：新增受支援的 card_type 取值 virtual_g（虛擬卡 - G 類）。非破壞性變更——無新增端點、無 schema 變化；未整合 G 卡的客戶端不受影響。
• 8 個 OpenAPI endpoint：
  • POST /api/v1/openapi/card_headers/list
  • POST /api/v1/openapi/card_configs/list
  • POST /api/v1/openapi/cards/list
  • POST /api/v1/openapi/card/apply
  • POST /api/v1/openapi/card/first_deposit/preview
  • POST /api/v1/openapi/card/recharge
  • POST /api/v1/openapi/card/info
  • POST /api/v1/openapi/webhook_events/list
• HMAC-SHA256 鑑權（4 個 header）
• 冪等鍵支援（/card/apply / /card/recharge）
• Webhook 推送：webhook.test / card.opened / card.open_failed / card.recharged / card.recharge_failed / card.closed / card.status_changed
• /card/info 透過 with_sensitive=true 選擇性返回完整 PAN / CVV / 到期日 / 持卡人姓名 —— 需憑證被授予該訪問權且卡處於 active 狀態。預設關閉，開通需審批。

欄位封裝規則

• 所有對外 ID 是帶業務字首的字串（card_ / pkg_ / hdr_ / txn_ / evt_），當作不透明 token 使用。
• 資產引用使用 ISO 4217 幣種程式碼 / 資產符號（字串，不暴露數字 ID）。
• card_type 全小寫業務程式碼（如 virtual_v）。
• 充值 status 用業務碼：2 成功 / 3 失敗。
• 開卡 / 銷卡 webhook status 用字串：opened / open_failed / closed。
• 內部欄位（DB 主鍵、提供方訂單引用、中間計算值、內部標籤等）不會透過響應返回。

範圍

• 僅虛擬卡：virtual_l / virtual_p / virtual_v / virtual_r / virtual_g
• 不含實體卡 / 轉賬介面（計劃在後續版本）

計劃（後續版本）

僅供參考，實際以發版為準

• 獨立沙箱環境
• 暴露 GET /openapi.json（自動生成的 OpenAPI 3.0 spec）
• 暴露 GET /openapi.postman.json（自動生成的 Postman Collection）

相容性承諾

• 同 major 版本（v1.x）內：只新增、不刪欄位
• 預設值、約束（長度、型別）不會向後不相容地變
• message_key 一旦釋出永久穩定
• 刪除欄位或改語義會升 major 版本並保留舊版至少 6 個月

反饋

• 郵箱：[email protected]