跳转到主要内容
本快速入门将演练完整的“发送卡片”生命周期。你将创建预发布应用、铸造具备范围的 Bearer 令牌、选择卡片项目、检索有资金的消费账户、生成托管虚拟卡链接、体验收件人激活流程、验证发卡，然后停用未使用的链接。 完成后，你将成功执行每个公开的“发送卡片”操作：
  • generateVCShareLinks
  • getVCShareLinks
  • deactivateVCShareLinks
——全部在沙盒环境中进行，不会发生任何真实客户资金流动。
先决条件
  • 一个 Fluz 账户——你将在下方步骤 1–2 中创建预发布 API 凭据并铸造具备范围的访问令牌。
  • 请求会发送到 沙盒 GraphQL 端点。托管收件人链接使用标准的 Fluz 激活体验，但所有 API 操作都使用你的预发布环境。
  • 你的账户必须启用发送卡片（send_virtual_cards_enabled），否则每个发送卡片操作都会返回权限错误。
  • 本快速入门使用有资金的 Spend Account（消费账户） 作为资金来源。卡片在被领取时才会注资，而不是在生成链接时。

​
在你开始之前

除铸造令牌（步骤 2）外，本指南中的每个请求都使用你的 Bearer 访问令牌发送到 Fluz GraphQL API。
下面的每个 GraphQL 操作都使用此端点和你的 Bearer 令牌。唯一的例外是步骤 2，它通过 OAuth 服务用你的应用凭据交换访问令牌。

​
完整流程

创建预发布应用

创建一个 Fluz 账户，然后打开开发者控制台并创建一个 Staging（预发布） 应用。当你的应用创建完成，你将获得：
  • clientId
  • clientSecret
将这两个值妥善保存。你的 clientSecret 只会显示一次。如果你尚未创建预发布应用，请参见 准备你的账户。

用凭据换取具备范围的 Bearer 令牌

将你的应用凭据发送至 OAuth 服务，生成短期有效的用户访问令牌。该令牌将用于授权后续的所有“发送卡片”操作。
保存返回的 accessToken。你将按如下方式使用它：
用于后续的每一个请求。
CREATE_SHARE_LINK 授权所有“发送卡片”操作。本快速入门还请求了 LIST_PAYMENT，以便你能检索为托管卡片提供资金的消费账户。
不要在浏览器或移动应用中暴露你的 clientSecret。**在服务端生成 Bearer 令牌，并仅将访问令牌转发给你的客户端。

检索有资金的消费账户（Spend Account）

托管虚拟卡从你的某个 Spend Account（消费账户） 注资。与常规虚拟卡不同，在生成链接时不会预留资金。相反，仅当收件人成功领取卡片时，所选消费账户才会被扣款。检索你可用的消费账户。
保存 userCashBalanceId。你将在生成托管卡链接时提供该值。
所选消费账户必须属于你的账户，并且在收件人领取卡片时拥有足够资金可用。如果在领取时可用余额不足，发卡将失败。

选择卡片项目

每张托管卡都基于某个虚拟卡**优惠（offer）**发行。该优惠决定发行项目、可用奖励，以及适用于每张生成卡片的限额。检索你的账户可用的优惠。
保存你希望发行所用项目的 offerId。
所选优惠必须：
  • 处于活动状态
  • 启用了分享
如果生成失败是因为该优惠不符合“发送卡片”资格，请与 Fluz 代表确认哪些优惠已启用托管分享。

生成两个托管卡链接

现在可以创建托管的“发送卡片”链接了。每个生成的链接代表一张未来的虚拟卡。在此阶段：
  • 尚未发行任何卡片。
  • 尚未扣除任何资金。
  • 每个链接都以 PENDING 状态开始。
仅当有收件人领取链接时，所选消费账户才会被扣款。在本快速入门中我们将生成两个链接：
  • 链接 A——你将以收件人身份领取它。
  • 链接 B——你将保持未领取，稍后用于撤销演示。
响应会为每张生成的卡片返回一个托管激活 URL。保存这两个 URL。我们将把它们称为：
  • 链接 A
  • 链接 B
在本快速入门的其余部分中使用。

​
了解生成设置

​
cardLimit
Int
必填
每张卡在被领取时加载的金额。每张生成的卡片都会获得自己独立的限额。
​
offerId
UUID
必填
要发行的托管虚拟卡项目。该优惠必须处于活动状态并启用“发送卡片”。
​
quantity
Int
必填
要生成的托管链接数量。每个请求的数量都会创建一个分享请求和一个托管 URL。
​
shareMethod
ShareMethodType
必填
控制收件人如何接收他们的链接。
  • GENERATE_URL 返回托管 URL 供你自行分发。
  • EMAIL 自动向收件人发送电子邮件。
  • PHONE_NUMBER 向收件人发送短信。
​
userCashBalanceId
UUID
必填
为每张生成卡片提供资金的消费账户。尽管该字段在 GraphQL 架构中看似可选，但在实际使用中是必填的。
​
daysUntilExpiration
Int
收件人可领取托管链接的时长。如省略，则使用项目默认值。生成的到期日也会成为已发行卡片的锁定日期。
你也可以不自行分发托管 URL，由 Fluz 向每位收件人发送他们自己的激活链接。

​
电子邮件

​
短信

收件人列表长度必须与 quantity 完全一致。如果不匹配，将验证失败并且不会创建任何链接。手机号码必须：
  • 包含国家代码
  • 不包含空格
  • 以字符串形式提供
示例：
生成托管链接并不会预留资金。如果在收件人领取卡片时，所选消费账户的可用余额不足，发卡将失败。
生成响应有意只返回托管 URL。它不会返回：
  • shareRequestBatchId
  • shareRequestDisplayId
你将在下一步中检索这些信息。

检索已生成的分享请求

虽然你已经拥有托管 URL，但通常你还需要底层的分享请求记录。这些记录包含：
  • 生命周期状态
  • 批次标识符
  • 显示 ID
  • 已发行虚拟卡 ID
  • 到期信息
在生成之后，立即检索你的待处理分享请求。
将返回的每个 linkUrl 与生成时返回的 URL 进行匹配。保存：
  • 共享的 shareRequestBatchId
  • 两个 shareRequestDisplayId 值
你将在稍后停用未使用链接时用到它们。此时两个链接都应为：
这确认了：
  • 链接已成功创建
  • 尚无收件人领取
  • 尚未发行任何虚拟卡

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

在浏览器中打开链接 A。这正是你的收件人看到的体验。托管流程引导收件人完成卡片激活，无需任何 API 集成。在激活过程中，收件人将：
  1. 打开托管激活页面。
  2. 登录或创建 Fluz 账户。
  3. 完成身份验证。
  4. 完成双重身份验证。
  5. 如未留存，添加账单地址。
  6. 创建卡片 PIN。
  7. 收到他们的托管虚拟卡。
仅在完成最后一步后，Fluz 才会：
  • 发行虚拟卡
  • 从你的消费账户为其注资
  • 将其分配给收件人
收件人成为仅该卡片的授权持有人。他们不会获得以下访问权限：
  • 你的 Fluz 账户
  • 你的消费账户
  • 你的余额
  • 任何其他已生成的卡片
卡片发行后，收件人可以：
  • 查看卡片
  • 在线消费
  • 将卡添加至 Apple Pay 或 Google Wallet（如受支持）
  • 查看后续交易
保持链接 B 不操作。我们将在下一部分演示链接撤销。

验证卡片已发行

在收件人领取链接 A后，再次检索分享请求。这次你会看到已领取的链接从 PENDING 变为 ISSUED。
你的两个链接现在应处于不同的生命周期状态。出现 virtualCardId 表明发卡已成功完成。
每个托管的“发送卡片”都会经历四种生命周期状态之一。只有 PENDING 状态的链接可以被停用。一旦卡片达到 ISSUED，停用原始链接不会撤销该卡片。

停用未使用的链接

假设第二位收件人并不需要他们的卡片，或者某个批次意外生成。你可以使用以下任一方式撤销任何未被领取的托管链接：
  • shareRequestBatchIds
  • shareRequestDisplayIds
在本快速入门中，我们将使用其显示 ID 仅停用链接 B。
停用会立即阻止该托管链接被领取。如果收件人之后打开该链接，他们将看到已到期或已撤销的体验，而不是激活流程。
停用只会影响未被领取的链接。如果收件人已经领取了卡片（ISSUED 或 USED），则无法再通过托管链接撤销它。要停止已发行卡片的消费，请使用适当的虚拟卡生命周期控制，例如 锁定虚拟卡。

确认最终生命周期

最后再检索一次分享请求。
你已经完成了完整的“发送卡片”生命周期演练。至此，你已经成功使用了三个公开的“发送卡片”操作：
  • ✅ generateVCShareLinks
  • ✅ getVCShareLinks
  • ✅ deactivateVCShareLinks

​
大功告成 🎉

你已完成托管“发送卡片”的全流程——从生成、收件人激活、生命周期跟踪到链接撤销。 在此过程中你已：
  • 生成托管虚拟卡链接。
  • 选择为收件人卡片提供资金的消费账户。
  • 检索并跟踪分享请求记录。
  • 以收件人身份领取托管卡片。
  • 验证从 PENDING 到 ISSUED 的状态转换。
  • 撤销未使用的托管链接。
  • 确认最终的 EXPIRED 状态。
接下来，你可以探索更高级的“发送卡片”工作流。

发送卡片概览

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

生成分享链接

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

获取消费账户

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

管理虚拟卡

在卡片已发行给收件人后进行锁定与管理。
想了解更多？通过 support@fluz.app 联系我们，与专家沟通或申请演示。