您的第一筆虛擬卡消費

本快速入門將帶你從全新的 Fluz 帳戶走到成功發出並可用的虛擬卡。你將註冊應用程式、鑄造具範圍的存取權杖，接著瀏覽卡片方案，依你的使用情境建立並設定卡片、揭露卡片細節，並觀察其交易 — 全都在沙盒環境中，無任何真實金流發生。

先決條件

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

開始之前

除了鑄造你的權杖（步驟 2）之外，每個呼叫都是送至單一 GraphQL 端點的 POST 請求，並以你的 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 應用程式。當憑證顯示時，請複製你的 clientId 與 clientSecret —— secret 只會顯示一次。完整教學： Prepare your accounts。

以憑證交換存取權杖

從你的應用程式憑證鑄造短期、具範圍的使用者存取權杖。此呼叫會送至 OAuth 服務；後續所有呼叫都使用回傳的權杖作為 Bearer 憑證。

    curl -X POST https://oauth-service.fluzapp.com/graphql \
      -H "Content-Type: application/json" \
      -d '{
        "query": "mutation ($clientId: String!, $clientSecret: String!, $scopes: [Scope!]!) { generateUserAccessToken(clientId: $clientId, clientSecret: $clientSecret, scopes: $scopes) { accessToken expiresIn scopes } }",
        "variables": {
          "clientId": "<APPLICATION_CLIENT_ID>",
          "clientSecret": "<APPLICATION_CLIENT_SECRET>",
          "scopes": ["MANAGE_PAYMENT", "CREATE_VIRTUALCARD", "EDIT_VIRTUALCARD", "REVEAL_VIRTUALCARD", "PCI_COMPLIANCE"]
        }
      }'

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

儲存回傳的 accessToken，並在下方每個請求以 Authorization: Bearer <accessToken> 夾帶。權杖為短期有效（expiresIn 以秒為單位）—— 請在伺服器端鑄造並於到期前更新。完整細節： API credentials。

Scope 會限定權杖的能力 — 僅包含你的流程所需：MANAGE_PAYMENT 用於為你的餘額加值、CREATE_VIRTUALCARD 用於瀏覽方案與發卡、REVEAL_VIRTUALCARD + PCI_COMPLIANCE 用於揭露卡片與拉取其交易、EDIT_VIRTUALCARD 用於日後鎖卡、解鎖或編輯卡片。

絕勿在瀏覽器或行動端用戶端暴露 clientSecret。請在伺服器端鑄造權杖，並只轉發該權杖。

為你的 Fluz 餘額加值

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

手動，透過 sandbox Fluz website。
程式化，透過 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": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "programName": "Virtual Card",
            "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
`ed669305-5e43-40a0-9a25-7a15ed174628`	Virtual Card	1.5%
`b23630f6-8d91-43df-84aa-a541e7691197`	Virtual Card - Mastercard Prepaid	1.5%
`592c394e-26cc-44ac-a145-a5f81301fe77`	Brand Locked Virtual Card - Mastercard Prepaid	1.5%

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

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

使用 createVirtualCard 發卡。輸入中的設定會將通用卡片轉為專用卡片 —— 請選擇符合你目標的模式：

一次性購買
具每月上限的訂閱
有預算且限期的卡片

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

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe12",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "spendLimit": 150.00,
            "lockCardNextUse": true,
            "cardNickname": "Vendor payment — Acme invoice #1042"
          }
        }

專用於單一循環扣款的卡片。spendLimitDuration: MONTHLY 會在每月重置上限，因此超過上限的漲價或重複請款會自動被拒。

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe13",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "spendLimit": 29.99,
            "spendLimitDuration": "MONTHLY",
            "cardNickname": "SaaS — analytics subscription"
          }
        }

用於專案或旅程且有明確結束日期的卡片。lockDate 會在該日凍結卡片（預設為建立後 47 個月），並停用 usePrepaymentBalance / useRewardsBalance 使其僅從指定的消費帳戶撥款 —— 可預期、單一來源的資金，利於清楚對帳。

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe14",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "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"
        }
      }
    }

設定總覽

spendLimit

Float

必填

卡片可被請款的最高金額 —— 你只會為實際使用的部分付費。必須符合你所選期間的方案上限。

spendLimitDuration

VirtualCardSpendLimitDuration

預設值:"LIFETIME"

上限如何重設。LIFETIME 對總消費設上限；DAILY / WEEKLY / MONTHLY 會形成滾動預算 —— 適合訂閱與團隊額度。

lockCardNextUse

Boolean

預設值:"false"

在首次成功使用後鎖定卡片 —— 針對一次性供應商付款的「虛擬單次使用卡」模式。

lockDate

String

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

卡片凍結的 yyyy-mm-dd 日期。將卡片的可用期限定在某個專案、行程或合約期間。

primaryFundingSource

VirtualCardFundingSource

預設值:"FLUZ_BALANCE"

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

usePrepaymentBalance / useRewardsBalance

Boolean

預設值:"true"

依預設，卡片也可能從預付（禮品卡）與回饋餘額扣款。將兩者都設為 false 可建立僅使用現金、且只從指定 userCashBalanceId 撥款的卡片 —— 對會計最清晰。

memo / transactionCategory

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 scope。

回應會以明文包含完整卡號與 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 scopes。省略 virtualCardIds 可拉取該帳戶下所有卡片的活動，並可用日期範圍過濾以建立對帳單式檢視。完整參考： Get Virtual Card Transactions。

用完了嗎？鎖卡吧（lockVirtualCard）

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

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

需要 EDIT_VIRTUALCARD scope。鎖定是可逆的 —— 參見 Unlock Virtual Card。

全部完成 🎉

你已針對特定任務發出一張虛擬卡 —— 選定方案、設定消費控管、揭露卡片並追蹤其活動。接下來可更深入：

編輯、鎖定與管理卡片

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

數位錢包與 PIN

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

大量發卡

一次建立最多 10,000 張卡。

將卡片發送給他人

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

想了解更多？ 歡迎聯絡我們： support@fluz.app 與專家對談或預約示範。

快速開始

Fluz 控制台

快速入門

您的第一筆虛擬卡消費

開始之前

完整流程

設定總覽

全部完成 🎉

編輯、鎖定與管理卡片

數位錢包與 PIN

大量發卡

將卡片發送給他人

​開始之前

​完整流程

​設定總覽

​全部完成 🎉

編輯、鎖定與管理卡片

數位錢包與 PIN

大量發卡

將卡片發送給他人

開始之前

完整流程

設定總覽

全部完成 🎉