发送卡片给他人

本快速开始将带你完整走一遍发送卡片的全生命周期。你将创建一个预发布应用、铸造带范围的 Bearer 令牌、选择卡片计划、检索有资金的消费账户、生成托管虚拟卡链接、体验收件人激活流程、验证发卡，然后停用一个未使用的链接。到最后，你将成功完成每个公开的发送卡片操作：

generateVCShareLinks
getVCShareLinks
deactivateVCShareLinks

—全部在沙盒中完成，不会有真实客户资金流转。

先决条件

一个 Fluz 账户 — 你将在下面的步骤 1–2 中创建预发布 API 凭证并铸造带范围的访问令牌。
请求发送到沙盒 GraphQL 端点。托管收件人链接使用标准的 Fluz 激活体验，但所有 API 操作都使用你的预发布环境。
你的账户必须已启用发送卡片（send_virtual_cards_enabled），否则每个发送卡片操作都会返回权限错误。
本快速开始使用已注资的 消费账户（Spend Account） 作为资金来源。卡片在被领取时才会注资，而不是在生成链接时。

开始之前

本指南中的每个请求都发送到 Fluz GraphQL API。铸造你的令牌（步骤 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 { offerId programName rewardValue } }"
  }'

下面的每个 GraphQL 操作都使用此端点和你的 Bearer 令牌。唯一的例外是步骤 2，它使用相同的端点但用你的 API Key（Authorization: Basic）进行认证以铸造令牌。

全流程

创建预发布应用

创建一个 Fluz 账户，然后打开开发者控制台并创建一个 Staging（预发布） 应用。应用创建完成后你将获得：

API Key
User ID
Account ID

将这三个值妥善保存。如果你还没有创建预发布应用，请参阅准备你的账户。

用凭证换取带范围的 Bearer 令牌

使用你的 API Key 调用 generateUserAccessToken，以生成一个短期有效的用户访问令牌。此令牌将授权后续的每个发送卡片操作。

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":[
        "CREATE_VIRTUALCARD",
        "LIST_PAYMENT"
      ]
    }
}'

{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": [
        "CREATE_VIRTUALCARD",
        "LIST_PAYMENT"
      ]
    }
  }
}

保存返回的 token。你将以如下形式使用它：

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

用于后续每个请求。

CREATE_VIRTUALCARD 授权所有发送卡片操作。本快速开始同时请求了 LIST_PAYMENT，以便你检索为托管卡片提供资金的消费账户（Spend Account）。

切勿在浏览器或移动应用中暴露你的 API Key。在服务器端生成 Bearer 令牌，并仅将访问令牌转发给你的客户端。

检索一个已注资的消费账户

托管虚拟卡由你的某个**消费账户（Spend Account）**提供资金。与常规虚拟卡不同，在生成链接时不会预留资金。相反，只有当收件人成功领取卡片时，所选消费账户才会被扣款。检索你可用的消费账户。

query GetSpendAccounts {
  getSpendAccounts {
    userCashBalanceId
    nickname
    availableBalance
    currency
  }
}

{
  "data": {
    "getSpendAccounts": [
      {
        "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "nickname": "Primary Spend Account",
        "availableBalance": 5000,
        "currency": "USD"
      }
    ]
  }
}

保存该 userCashBalanceId。你将在生成托管卡片链接时提供此值。

所选消费账户必须属于你的账户，并且在收件人领取卡片时必须有足够资金可用。如果在领取时可用余额不足，发卡将失败。

选择卡片计划

每张托管卡都基于一个虚拟卡**优惠（offer）**发行。该优惠决定发行计划、可用奖励以及适用于每张生成卡片的限制。检索你的账户可用的优惠。

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

{
  "data": {
    "getVirtualCardOffers": [
      {
        "offerId": "11111111-2222-3333-4444-555555555555",
        "programName": "Virtual Card",
        "rewardValue": "1.5%",
        "programLimits": {
          "dailyLimit": 500,
          "weeklyLimit": 2000,
          "monthlyLimit": 5000
        }
      }
    ]
  }
}

保存你希望发行的计划的 offerId。

所选优惠必须：

处于激活状态
已启用分享

如果生成失败是因为该优惠不符合发送卡片的条件，请与你的 Fluz 代表确认哪些优惠已启用托管分享。

生成两个托管卡片链接

你已准备好创建托管的发送卡片链接。每个生成的链接代表一张未来的虚拟卡。在此阶段：

尚未发行任何卡片。
尚未扣除任何资金。
每个链接都以 PENDING 状态开始。

所选消费账户仅在收件人领取链接时扣款。在本快速开始中，我们将生成两个链接：

链接 A — 你将以收件人身份领取此链接。
链接 B — 你将保持其未领取，以便稍后撤销。

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "daysUntilExpiration": 14,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8ac...c1",
        "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      ]
    }
  }
}

响应会为每张生成的卡片返回一个托管激活 URL。保存这两个 URL。我们将把它们称为：

链接 A
链接 B

贯穿本快速开始的其余部分。

了解生成设置

Int

必填

收件人领取时加载到每张托管卡上的金额。每张生成卡片都拥有各自独立的限额。

UUID

必填

要发行的托管虚拟卡计划。该优惠必须处于激活状态且已启用发送卡片。

Int

必填

要生成的托管链接数量。每个请求的数量都会创建一个分享请求和一个托管 URL。

控制收件人如何接收他们的链接。

GENERATE_URL 返回由你分发的托管 URL。
EMAIL 自动向收件人发送电子邮件。
PHONE_NUMBER 向收件人发送短信。

UUID

必填

为每张生成卡片提供资金的消费账户。尽管此字段在 GraphQL 架构中看似可选，但在实践中是必填的。

Int

收件人可用于领取托管链接的时长。如果省略，将使用计划的默认值。生成的到期日期也会成为已发行卡片的锁定日期。

改为通过电子邮件或短信发送卡片

除了自行分发托管 URL，Fluz 还可以向每位收件人发送他们自己的激活链接。

电子邮件

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": [
      "alice@example.com",
      "bob@example.com"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

短信

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": [
      "+18883606660",
      "+18885551234"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

收件人列表长度必须与 quantity 完全一致。如果不匹配，将验证失败并且不会创建任何链接。电话号码必须：

包含国家代码
不含空格
以字符串形式提供

示例：

+18883606660

生成托管链接不会预留资金。如果收件人领取卡片时所选消费账户没有足够的可用余额，发卡将失败。

生成响应特意仅返回托管 URL。它不会返回：

shareRequestBatchId
shareRequestDisplayId

你将在下一步中检索这些信息。

检索已生成的分享请求

虽然你已经拥有托管 URL，但通常你也会需要底层的分享请求记录。它们包含：

生命周期状态
批次标识符
展示用 ID
已发行虚拟卡的 ID
到期信息

在生成之后，立即检索你的待处理分享请求。

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    linkExpirationDate
    virtualCardId
    linkUrl
  }
}

{
  "input": {
    "shareObjectStatuses": [
      "PENDING"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

将每个返回的 linkUrl 与生成期间返回的 URL 进行匹配。保存：

共享的 shareRequestBatchId
两个 shareRequestDisplayId 值

你稍后将在停用未使用链接时使用它们。此时两个链接都应为：

Status: PENDING
Virtual Card ID: null

这确认了：

链接已成功创建
尚无收件人领取
尚未发行任何虚拟卡

以收件人身份领取其中一个链接

在浏览器中打开链接 A。这正是你的收件人所看到的体验。托管流程引导收件人在无需任何 API 集成的情况下完成卡片激活。在激活过程中，收件人会：

打开托管激活页面。
登录或创建一个 Fluz 账户。
完成身份验证。
完成双因素认证。
如未留存账单地址则添加一个账单地址。
创建卡片 PIN。
收到他们的托管虚拟卡。

只有在最后一步之后，Fluz 才会：

发行虚拟卡
从你的消费账户注资
将其分配给收件人

收件人成为仅该卡片的授权持有人。他们不会获得以下访问权限：

你的 Fluz 账户
你的消费账户
你的余额
任何其他生成的卡片

卡片发行后，收件人可以：

查看卡片
在线消费
将其添加到 Apple Pay 或 Google Wallet（在支持的地区）
查看后续交易

请保持链接 B 不变。我们将使用它在下一部分演示链接撤销。

验证卡片已发行

在收件人领取链接 A之后，再次检索分享请求。这一次，你将看到已领取的链接从 PENDING 转变为 ISSUED。

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
    linkUrl
  }
}

{
  "input": {
    "shareRequestBatchIds": [
      "BATCH123"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

你的两个链接现在应处于不同的生命周期状态。

链接	预期状态	含义
链接 A	`ISSUED`	收件人已成功领取卡片并创建了虚拟卡。
链接 B	`PENDING`	该链接尚未被领取。

出现 virtualCardId 表明发卡已成功完成。

理解发送卡片的状态

每个托管的发送卡片都会经历四个生命周期状态之一。

状态	含义
`PENDING`	托管链接已生成，但尚未被领取。
`ISSUED`	收件人已成功领取该链接并收到虚拟卡。
`USED`	已发行的卡片已完成至少一笔交易。
`EXPIRED`	托管链接自然过期或在被领取前被停用。

只有处于 PENDING 状态的链接才可以被停用。一旦卡片达到 ISSUED 状态，停用原始链接不会撤销该卡片。

停用未使用的链接

假设第二位收件人不再需要他们的卡片，或者误生成了一批链接。你可以使用以下任一方式撤销任何未领取的托管链接：

shareRequestBatchIds
shareRequestDisplayIds

在本快速开始中，我们将使用其展示用 ID 仅停用链接 B。

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

{
  "input": {
    "shareRequestDisplayIds": [
      "SR-000002"
    ]
  }
}

{
  "data": {
    "deactivateVCShareLinks": "1 share requests successfully deactivated!"
  }
}

停用会立即阻止该托管链接被领取。如果收件人之后打开该链接，他们将看到已过期或被撤销的体验，而不是激活流程。

停用仅影响未领取的链接。如果收件人已领取卡片（ISSUED 或 USED），则无法再通过托管链接撤销它。要停止对已发行卡片的消费，请使用相应的虚拟卡生命周期控制，例如锁定虚拟卡。

确认最终生命周期

最后再检索一次分享请求。

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
  }
}

{
  "input": {
    "shareRequestBatchIds": [
      "BATCH123"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "EXPIRED",
        "virtualCardId": null
      }
    ]
  }
}

你现在已经完成了发送卡片的完整生命周期演练。

链接	最终状态	结果
链接 A	`ISSUED`	已成功被收件人领取并发行。
链接 B	`EXPIRED`	在被领取前成功撤销。

至此，你已成功使用了全部三个公开的发送卡片操作：

✅ generateVCShareLinks
✅ getVCShareLinks
✅ deactivateVCShareLinks

大功告成 🎉

你已完成托管发送卡片的完整生命周期——从生成、收件人激活、生命周期跟踪到链接撤销。在此过程中你已：

生成托管虚拟卡链接。
选择为收件人卡片提供资金的消费账户。
检索并跟踪分享请求记录。
以收件人身份领取托管卡。
验证从 PENDING 到 ISSUED 的转变。
撤销一个未使用的托管链接。
确认最终的 EXPIRED 状态。

接下来，你可以探索更高级的发送卡片工作流。

发送卡片概览

收件人体验、计划规则、生命周期状态以及完整的错误参考。

生成分享链接

每个发送卡片操作的详细 API 参考。

获取消费账户

检索并管理用于为托管卡片提供资金的消费账户。

管理虚拟卡

在卡片发行给收件人后进行锁定与管理。

想了解更多？通过 support@fluz.app 与我们联系，与专家交流或申请演示。

快速开始

Fluz 控制台

快速入门

发送卡片给他人

开始之前

全流程

了解生成设置

电子邮件

短信

大功告成 🎉

发送卡片概览

生成分享链接

获取消费账户

管理虚拟卡

​开始之前

​全流程

​了解生成设置

​电子邮件

​短信

​大功告成 🎉

发送卡片概览

生成分享链接

获取消费账户

管理虚拟卡

开始之前

全流程

了解生成设置

电子邮件

短信

大功告成 🎉