您的第一筆虛擬卡購買

本快速入門將從全新的 Fluz 帳戶開始，帶你走到成功發卡並可用於消費的虛擬卡。你將註冊應用程式、鑄造具範圍的存取權杖，接著瀏覽卡片方案，建立符合你的使用情境的卡片、揭示其詳細資料，並觀察其交易 — 全都在沙盒環境中進行，不會有真實金流發生。

先決條件

一個 Fluz 帳戶 — 你將在下方步驟 1–2 建立 Staging API 憑證並鑄造存取權杖。
請將請求送至 sandbox GraphQL 端點。此處不會對真實卡片收費 — 請見 Staging vs. Live Environment。
每個 mutation 都需要唯一的 idempotencyKey（用戶端產生的 UUID），以確保請求只會被處理一次 — 請見 Idempotency。

開始之前

每次呼叫皆為 POST 至同一個 GraphQL 端點。鑄造權杖（步驟 2）時以 API Key 驗證；其餘呼叫皆以 bearer 權杖驗證：

POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>
Content-Type: application/json

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetVirtualCardOffers { getVirtualCardOffers { offerId programName rewardValue } }"
  }'

Staging 附帶可立即發卡的 測試卡片方案，而你的沙盒帳戶也包含已預先新增的測試銀行卡做為資金來源。完整沙盒資料集請見 Test Merchants 與 Test Bank Cards。

全流程

註冊並登錄應用程式

於 fluz.app 建立 Fluz 帳戶，然後開啟 Developer Console 並建立新的 Staging 應用程式。當憑證顯示時，請複製你的 API Key、User ID 與 Account ID。完整教學： Prepare your accounts。

以憑證交換存取權杖

使用你的 API Key 鑄造一個短效、具範圍的使用者存取權杖。此呼叫送往相同的 GraphQL 端點，並以 Authorization: Basic <YOUR_API_KEY> 授權；後續所有呼叫都以回傳的權杖作為 Bearer 認證。

    curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
      -H "Authorization: Basic <YOUR_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "mutation ($userId: UUID!, $accountId: UUID!, $scopes: [ScopeType!]!) { generateUserAccessToken(userId: $userId, accountId: $accountId, scopes: $scopes) { token scopes } }",
        "variables": {
          "userId": "<YOUR_USER_ID>",
          "accountId": "<YOUR_ACCOUNT_ID>",
          "scopes": ["MANAGE_PAYMENT", "CREATE_VIRTUALCARD", "EDIT_VIRTUALCARD", "REVEAL_VIRTUALCARD", "PCI_COMPLIANCE"]
        }
      }'

    {
      "data": {
        "generateUserAccessToken": {
          "token": "eyJhbGciOi...",
          "scopes": ["MANAGE_PAYMENT", "CREATE_VIRTUALCARD", "EDIT_VIRTUALCARD", "REVEAL_VIRTUALCARD", "PCI_COMPLIANCE"]
        }
      }
    }

儲存回傳的 token，並在下列每個請求的 Authorization: Bearer <token> 中使用。權杖為短效 — 請在伺服器端鑄造，並在過期時以相同的 mutation 鑄造新權杖（見 Refresh an expired access token）。完整細節： API credentials。

權杖的範圍（scopes）決定可執行的動作 — 僅包含你的流程所需：MANAGE_PAYMENT 用於為餘額加值、CREATE_VIRTUALCARD 用於瀏覽方案與發卡、REVEAL_VIRTUALCARD + PCI_COMPLIANCE 用於揭示卡片與擷取其交易，EDIT_VIRTUALCARD 用於之後鎖卡、解鎖或編輯。

切勿在瀏覽器或行動端用戶端暴露你的 API Key。請在伺服器端鑄造權杖，並僅轉發該權杖。

為你的 Fluz 餘額加值

當虛擬卡被使用時，資金會自你的帳戶出帳 — 預設來自你的 Fluz 餘額（FLUZ_BALANCE）。請確保可用餘額足以涵蓋你計畫設定的消費上限。你可以透過兩種方式加值：

手動，透過 sandbox Fluz 網站。
程式化，透過 depositCashBalance mutation。

透過 API 加值（depositCashBalance）

使用 getWallet 取得資金來源 ID，然後執行加值：

      mutation depositCashBalance($input: DepositCashBalanceInput!) {
        depositCashBalance(input: $input) {
          balances {
            cashBalance { availableBalance totalBalance pendingBalance }
          }
        }
      }

      {
        "input": {
          "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
          "amount": 200.00,
          "depositType": "CASH_BALANCE",
          "bankCardId": "<YOUR_TEST_BANK_CARD_ID>"
        }
      }

gift card Quickstart 以完整細節示範此步驟，包括使用 getWallet 取得付款方式 ID。

偏好改由連結的銀行帳戶為卡片出資嗎？請在發卡（步驟 5）時設定 primaryFundingSource: BANK_ACCOUNT 並傳入 bankAccountId — 不需預先加值餘額。

瀏覽卡片方案並選擇一個 offer

每張虛擬卡皆基於一個 卡片方案（一個「offer」）發行：方案決定網路、發卡銀行、回饋率，以及你的卡必須遵守的消費上限。使用 getVirtualCardOffers 擷取你帳戶可用的方案。

    query GetVirtualCardOffers {
      getVirtualCardOffers {
        offerId
        programName
        bin
        bankName
        rewardValue
        programLimits {
          dailyLimit
          weeklyLimit
          monthlyLimit
        }
      }
    }

    {
      "data": {
        "getVirtualCardOffers": [
          {
            "offerId": "5b22153c-7c1e-4a66-9d2c-e786da7e9393",
            "programName": "Virtual Card - Mastercard Prepaid",
            "bin": "543210",
            "bankName": "Bank of Examples",
            "rewardValue": "1.5%",
            "programLimits": {
              "dailyLimit": "500.00",
              "weeklyLimit": "2000.00",
              "monthlyLimit": "5000.00"
            }
          }
        ]
      }
    }

Offers 依 rewardValue 排序，因此回饋最高的方案會優先出現。你可以用選擇性的 input 篩選 — cardType（DEBIT / PREPAID）、cardNetwork（MASTERCARD / VISA），以及 cardBrandLocked。完整參考： Get Virtual Card Offers。在沙盒環境下，以下測試方案永遠可用：

Offer ID	Program Name	Reward Value
`5b22153c-7c1e-4a66-9d2c-e786da7e9393`	Virtual Card - Mastercard Prepaid	1.5%
`e5d209d2-97b2-4636-9531-b3a459e34651`	Brand Locked Virtual Card - Mastercard Prepaid	1.5%
`0a6f66ec-a615-47cb-a850-ef971f7054b8`	Single Load Virtual Card - Mastercard Prepaid	1.5%
`490032ad-2e67-4ef0-92ff-cd7071332716`	Reloadable Virtual Card - Mastercard Prepaid	1.5%

不確定該選哪個方案？Virtual Card 是通用、可任意消費的方案 — 是本快速入門的正確預設。Brand Locked 僅能在單一商家使用，Single Load 僅加值一次並用至歸零，Reloadable 可於建立後再度加值。完整說明請見 Test Virtual Card Offers。

請保存你所選的 offerId，並留意其 programLimits — 你在下一步設定的 spendLimit 必須落在該方案對應期間的限制內。

建立卡片，並依你的使用情境設定

使用 createVirtualCard 發卡。輸入中的設定會把一張泛用卡片轉換成針對目的打造的卡片 — 選擇最符合你要打造之模式的設定：

一次性購買
訂閱制，含每月上限
有預算且有時限的卡片

僅供單筆交易的卡片。將 spendLimit 設為購買金額，並設定 lockCardNextUse: true，使卡片在第一次授權後自動鎖定 — 之後不可再被扣款。

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe12",
            "offerId": "5b22153c-7c1e-4a66-9d2c-e786da7e9393",
            "spendLimit": 150.00,
            "lockCardNextUse": true,
            "cardNickname": "Vendor payment — Acme invoice #1042"
          }
        }

專供定期扣款的卡片。spendLimitDuration: MONTHLY 會在每月重置上限，因此若價格上漲或發生重複扣款超過上限時，將自動被拒。

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe13",
            "offerId": "5b22153c-7c1e-4a66-9d2c-e786da7e9393",
            "spendLimit": 29.99,
            "spendLimitDuration": "MONTHLY",
            "cardNickname": "SaaS — analytics subscription"
          }
        }

用於專案或旅程，且有明確的結束日期。lockDate 會在該日凍結卡片（預設為建立日起 47 個月後），並關閉 usePrepaymentBalance / useRewardsBalance，使其僅從指定的消費帳戶扣款 — 以可預測的單一資金來源，達到乾淨的對帳。

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe14",
            "offerId": "5b22153c-7c1e-4a66-9d2c-e786da7e9393",
            "spendLimit": 2000.00,
            "lockDate": "2026-09-30",
            "userCashBalanceId": "<SPEND_ACCOUNT_ID>",
            "usePrepaymentBalance": false,
            "useRewardsBalance": false,
            "cardNickname": "Q3 conference travel"
          }
        }

以上三種皆呼叫同一個 mutation：

    mutation createVirtualCard($input: CreateVirtualCardInput!) {
      createVirtualCard(input: $input) {
        virtualCardId
        cardholderName
        virtualCardLast4
        expiryMonth
        expiryYear
        status
        cardType
        initialAmount
        usedAmount
        createdAt
      }
    }

    {
      "data": {
        "createVirtualCard": {
          "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
          "cardholderName": "xyz789",
          "virtualCardLast4": "7890",
          "expiryMonth": "12",
          "expiryYear": "27",
          "status": "ACTIVE",
          "cardType": "MULTI_USE",
          "initialAmount": 150.00,
          "usedAmount": 0,
          "createdAt": "2026-07-09T10:00:00Z"
        }
      }
    }

設定總覽

Float

必填

卡片可被扣款的最高金額 — 你僅會為實際使用部分付費。必須落在你所選期間的方案限制內。

VirtualCardSpendLimitDuration

預設值:"LIFETIME"

限額如何重置。LIFETIME 對總消費設上限；DAILY / WEEKLY / MONTHLY 則為滾動預算 — 是訂閱與團隊配額的理想選擇。

Boolean

預設值:"false"

在首次成功使用後鎖定卡片 — 用於一次性廠商付款的「虛擬一次性卡」模式。

String

預設值:"建立日起 47 個月"

卡片凍結的 yyyy-mm-dd 日期。將卡片時間盒化以對應專案、旅程或合約期間。

VirtualCardFundingSource

預設值:"FLUZ_BALANCE"

消費的資金來源。FLUZ_BALANCE 使用你的預先加值餘額；BANK_ACCOUNT 直接自連結的銀行帳戶扣款（需提供 bankAccountId）。

Boolean

預設值:"true"

預設情況下，卡片也可能使用預付（禮品卡）與回饋餘額。將兩者皆設為 false 可建立僅使用現金、且只自指定 userCashBalanceId 扣款的卡片 — 對帳最乾淨。

String

附加於最終交易的選用費用中繼資料 — 類別會在首次使用時建立。請見 Add Expense Details。

帳單地址： 若你的帳戶尚未有存檔地址，請傳入 billingAddress（或已儲存的 userAddressId）。該地址必須為真實、可投遞的美國地址 — 不可為郵政信箱（PO Box）— 否則建立會以 VC-0025 失敗。請見 Address Formatting Requirements。

請保留回應中的 virtualCardId — 下一步你將用它來揭示卡片。若發卡失敗，請檢查 Virtual Card Error Codes。

揭示卡片詳細資訊

建立回應刻意不包含敏感卡號。使用 revealVirtualCardByVirtualCardId 取得完整 PAN、CVV 與到期資訊 — 這些是你（或你的使用者）在結帳時輸入，或加入行動錢包所需的資料。

    mutation RevealVirtualCard($virtualCardId: UUID!) {
      revealVirtualCardByVirtualCardId(virtualCardId: $virtualCardId) {
        cardNumber
        expiryMMYY
        cvv
        cardHolderName
        billingAddress {
          streetAddress
          postalCode
          city
          state
        }
      }
    }

    {
      "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11"
    }

需具備 REVEAL_VIRTUALCARD 範圍。

回應包含明文的完整卡號與 CVV。請將其視為敏感持卡人資料 — 僅透過 TLS 傳輸、切勿記錄至日誌，並僅顯示給授權使用者。

多數線上結帳不需要 PIN — 但若你的情境需要（或你想使用感應支付），請見 Set Virtual Card PIN 與 Digital Wallet Push Provisioning 以一鍵將卡片加入 Apple Pay 或 Google Pay。

消費，然後觀察活動

在卡片網路支援的任一處使用揭示後的卡片資訊，並遵循你設定的限制。接著使用 getVirtualCardTransactions 擷取該卡的活動以確認扣款 — 同一查詢也可用於支出儀表板、對帳與拒付監控。

    query GetVirtualCardTransactions {
      getVirtualCardTransactions(
        input: {
          virtualCardIds: ["07df5653-43a8-4532-9881-3ab5857bbe11"]
          filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
          paginate: { limit: 20, offset: 0 }
        }
      ) {
        virtualCardId
        transactions {
          transactionDate
          transactionType
          transactionStatus
          transactionAmount
          merchantName
          mcc
        }
      }
    }

    {
      "data": {
        "getVirtualCardTransactions": [
          {
            "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
            "transactions": [
              {
                "transactionDate": "2026-07-09T14:22:31Z",
                "transactionType": "PURCHASE",
                "transactionStatus": "CLEARED",
                "transactionAmount": 42.17,
                "merchantName": "ACME OFFICE SUPPLY",
                "mcc": 5943
              }
            ]
          }
        ]
      }
    }

需具備 PCI_COMPLIANCE 與 REVEAL_VIRTUALCARD 範圍。若省略 virtualCardIds，可擷取該帳戶底下所有卡片的活動，並可依日期範圍篩選以建立對帳單樣式的檢視。完整參考： Get Virtual Card Transactions。

用完卡片了嗎？將其鎖定（lockVirtualCard）

設定了 lockCardNextUse 或 lockDate 的卡片會自動處理。要隨選鎖定其他卡片：

      mutation {
        lockVirtualCard(input: { virtualCardId: "07df5653-43a8-4532-9881-3ab5857bbe11" }) {
          virtualCardId
          locked
        }
      }

需具備 EDIT_VIRTUALCARD 範圍。鎖定可逆轉 — 請見 Unlock Virtual Card。

全部完成 🎉

你已針對特定工作成功發行一張虛擬卡 — 已選好方案、設定消費控管、揭示卡片，並追蹤其活動。接下來可以更進一步：

編輯、鎖定與管理卡片

變更現有卡片的限額、暱稱與鎖定日期。

數位錢包與 PIN

將卡片推送至 Apple Pay / Google Wallet，並設定 PIN。

批次發卡

在單一訂單中建立最多 10,000 張卡。

將卡片發送給他人

以連結、電子郵件或簡訊分發卡片給收件者。

想了解更多？ 請透過 support@fluz.app 與我們的專家聯繫或申請示範。

快速開始

Fluz 控制台

快速入門

您的第一筆虛擬卡購買

開始之前

全流程

設定總覽

全部完成 🎉

編輯、鎖定與管理卡片

數位錢包與 PIN

批次發卡

將卡片發送給他人

​開始之前

​全流程

​設定總覽

​全部完成 🎉

編輯、鎖定與管理卡片

數位錢包與 PIN

批次發卡

將卡片發送給他人

開始之前

全流程

設定總覽

全部完成 🎉