跳轉到主要內容
本快速入門示範如何在一個請求中發行 100 張虛擬卡。你將建立一筆非同步的大量訂單、在卡片建立過程中輪詢狀態，並擷取完整卡片詳細資料 — 無論你要發 10 張或 10,000 張，流程都相同。
先決條件
  • 一個具有測試環境應用程式的 Fluz 帳戶 — 任一快速入門的步驟 1–2，或參見準備你的帳戶與 API 憑證。
  • 具有 CREATE_VIRTUALCARD 權限範圍的權杖。
  • 有足夠可用餘額以支付訂單 — 100 張卡 × 你設定的消費上限。每次變更操作都需要唯一的 idempotencyKey — 參見冪等性。

​
完整流程

建立大量訂單

一次 createVirtualCardBulkOrder 呼叫可建立全部 100 張卡。orderItems 中的每個項目都是一個卡片設定並包含 quantity — 以下為 100 張相同的單次使用撥付款卡：
offerId 會套用到訂單中的每一張卡；如需混合設定，可新增更多 orderItems 項目（例如，80 張 × 25的單次使用，加上20張×25 的單次使用，加上 20 張 × 100 的每月卡）。lockCardNextUse: true 會讓每張卡於第一次扣款後自我失效 — 這是標準的撥付模式。
大量訂單為非同步 — 回應只會提供 orderId 與 PENDING，不會直接回傳卡片。請保存 orderId；它是後續所有操作的依據。

輪詢訂單直到完成

使用 getVirtualCardBulkOrderStatus 追蹤進度。當訂單仍為 PENDING 時，卡片會逐步產生：
以退避策略進行輪詢，直到 orderStatus 變為 COMPLETED（或 FAILED）— 在待處理期間，successfulCardCreations 會逐步接近 totalCards，而 virtualCards 也會逐步填入。
回應中包含以純文字呈現的完整卡號（PAN）、CVV 與到期日。請視為敏感持卡人資料：僅透過 TLS 傳輸、切勿記錄日誌、且只提供給授權使用者檢視。

處理部分失敗

大量訂單可能部分成功：在完成的訂單上出現 successfulCardCreations: 98, failedCardCreations: 2，代表有 98 張有效可用的卡，另有 2 張需要重試。請比較這些計數與 totalCards 以核對，然後只重新發行短缺的卡 — 並使用新的 idempotencyKey，因為這是新訂單：
持續失敗通常與方案限制或資金有關 — 請檢查虛擬卡錯誤代碼以及你的可用餘額。

​
大功告成 🎉

只需一個請求就能取得一百張已設定好的卡，再配合即可用於正式環境的輪詢迴圈。接下來：

取得虛擬卡交易

監控整批的消費 — 每次查詢最多 10 張卡，或依日期查詢整個帳戶。

將卡片發送給收件人

要發送給組織外的人嗎？託管的領取連結可為你處理導入流程。
想了解更多？ 歡迎聯絡我們： support@fluz.app 與專家對談或預約示範。