您的首次虚拟卡购买

本快速入门将带你从全新的 Fluz 账户到成功开出并可用的虚拟卡。你将注册一个应用、铸造带作用域的访问令牌，然后浏览卡计划，为你的用例创建并配置虚拟卡，显示其详细信息，并查看其交易——全部在沙盒中进行，不涉及任何真实资金流转。

前置条件

一个 Fluz 账户——你将按下方步骤 1–2 创建暂存环境的 API 凭证并铸造访问令牌。
所有请求发送到沙盒 GraphQL 端点。这里不会扣真实卡——参见 Staging vs. Live Environment。
每个 mutation 都需要唯一的 idempotencyKey（客户端生成的 UUID），以确保请求只被处理一次——参见 Idempotency。

开始之前

每次调用都是向单一 GraphQL 端点发起的 POST 请求。铸造令牌（步骤 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 } }"
  }'

沙盒自带可用的测试卡计划，你的沙盒账户也已预添加测试银行借记卡作为资金来源。查看 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。

作用域控制令牌的能力——仅包含你的流程所需的权限：MANAGE_PAYMENT 用于为余额充值，CREATE_VIRTUALCARD 用于浏览计划并开卡，REVEAL_VIRTUALCARD + PCI_COMPLIANCE 用于查看卡号和拉取交易，EDIT_VIRTUALCARD 用于稍后锁卡、解锁或编辑。

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

为 Fluz 余额入金

虚拟卡在被使用时会从你的账户扣款——默认从你的 Fluz 余额（FLUZ_BALANCE）中扣。请确保可用余额足以覆盖你计划设置的消费上限。你可以通过两种方式入金：

手动，通过沙盒版 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"
            }
          }
        ]
      }
    }

Offer 按 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 months from creation"

卡片冻结的 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

批量发行

将卡片发送给他人

开始之前

完整流程

设置一览

全部完成 🎉