你的第一笔虚拟卡消费

本快速入门将带你从一个全新的 Fluz 账户到一张已发行且可消费的虚拟卡。你将注册一个应用、铸造带作用域的访问令牌，然后浏览卡计划，创建为你的用例配置的卡片，展示其详细信息，并观察其交易——全部在沙盒环境中进行，不涉及真实资金流转。

先决条件

一个 Fluz 账户 —— 你将在下方步骤 1–2 中创建 Staging 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 仅显示一次。完整演练：准备你的账户。

用凭据换取访问令牌

使用你的应用凭据铸造一个短时效、带作用域的用户访问令牌。该调用发送至 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。

作用域控制令牌能做什么——仅包含你的流程所需内容：MANAGE_PAYMENT 为你的余额注资，CREATE_VIRTUALCARD 浏览计划并发行卡，REVEAL_VIRTUALCARD + PCI_COMPLIANCE 展示卡并拉取其交易，EDIT_VIRTUALCARD 之后用于锁卡、解锁或编辑卡片。

切勿在浏览器或移动端暴露 clientSecret。请在服务器端铸造令牌，并仅转发令牌。

为你的 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>"
        }
      }

礼品卡快速入门对该步骤进行了完整讲解，包括通过 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 作用域。

响应包含明文的完整卡号和 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

批量发行

将卡片发送给他人

开始之前

全流程

设置一览

大功告成 🎉