Skip to main content
本快速入門示範如何在一次請求中發行 100 張虛擬卡。你將建立一個非同步的大量訂單，在卡片建立期間輪詢其狀態，並擷取完整卡片詳情——無論是發 10 張或 10,000 張，都採用相同模式。
先決條件
  • 一個具備測試環境應用程式的 Fluz 帳戶——任一快速入門的步驟 1–2，或參見準備你的帳戶與 API 憑證。
  • 具備 CREATE_VIRTUALCARD 範圍的權杖。
  • 有足夠可用餘額以涵蓋訂單——100 張卡 × 你設定的消費上限。每個變更請求都需要唯一的 idempotencyKey——參見冪等性。

​
完整流程

建立大量訂單

一個 createVirtualCardBulkOrder 呼叫即可建立全部 100 張卡。orderItems 中的每個項目都是一個卡片設定，包含 quantity——此處為 100 張相同的單次使用撥款卡：
offerId 會套用到訂單中的每一張卡；若要混合設定，可新增更多 orderItems 項目（例如 20 張 25單次使用+80張25 單次使用 + 80 張 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，因為這是新訂單：
持續失敗通常與程式限制或資金有關——請檢查虛擬卡錯誤代碼以及你的可用餘額。

​
大功告成 🎉

一次請求就能取得 100 張完成設定的卡片，並搭配可直接上線使用的輪詢迴圈。接下來：

取得虛擬卡交易

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

將卡片發送給收件人

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