数字钱包推送开通（Push Provisioning）

使用 getCardProvisioningUrl 查询来铸造一个短期有效的 URL——当在终端用户的手机上打开时——会在设备上启动 Fluz，并将特定的虚拟卡添加到 Apple Pay（iOS）或 Google Pay（Android）。你可以以任意方式传递该 URL：二维码、短信、电子邮件，或应用内按钮。随后 Fluz 将处理钱包开通流程。

何时使用

在任何你通常会将虚拟卡交给用户、并希望他们无需输入卡号即可将其添加到手机钱包的地方。典型流程包括：

为用户创建卡片 offer 后，在屏幕上展示二维码。
通过短信或电子邮件将 URL 发送给持卡人。
在你自己的移动应用中嵌入“添加到 Apple Pay / Google Pay”按钮。

先决条件： 终端用户的 OAuth 访问令牌，且包含 CREATE_VIRTUALCARD scope，以及用于选择卡片的标识。可以是 createVirtualCard 返回的 virtualCardId，或账户可访问的 offerId。如果该 offer 尚未兑换为卡片，将在开通流程中创建一张。

基本认证（client_id / client_secret）在此查询上不被接受——必须是用户上下文的 Bearer 令牌。

查询

按卡片（推荐）：

query ProvisionCard($virtualCardId: String!) {
  getCardProvisioningUrl(input: { virtualCardId: $virtualCardId, platform: IOS }) {
    url
    expiresAt
  }
}

按 offer（当账户在该 offer 上最多仅持有一张活跃卡时）：

query ProvisionCard($offerId: String!) {
  getCardProvisioningUrl(input: { offerId: $offerId, platform: IOS }) {
    url
    expiresAt
  }
}

输入

只提供 virtualCardId 或 offerId 中的恰好一个。

字段	类型	必填	说明
`virtualCardId`	`String` (UUIDv4)	二选一	要开通的钱包卡片，由 `createVirtualCard` 返回。必须属于调用者账户且为 `ACTIVE`。更推荐此方式：可明确指向唯一卡片。
`offerId`	`String` (UUIDv4)	二选一	要开通的虚拟卡 offer。必须为激活状态、支持代币化，且对该用户账户可访问。仅当账户在该 offer 上至多持有一张活跃卡时才可解析。
`platform`	`ProvisioningPlatform`	否	关于用户将在哪打开 URL 的提示。默认 `IOS`。见下文——这不会将 URL 锁定到某个平台。

一个 offer 可在同一账户下支持多张卡片。一旦某个 offer 上存在多于一张活跃卡，offerId 将不再能唯一标识卡片，查询会返回 VirtualCard.AMBIGUOUS_CARD_SELECTION，而不是替你任选其一。如果你在同一 offer 下发行多张卡，请使用 virtualCardId。

`ProvisioningPlatform`

返回的 URL 具备平台感知能力：iOS 用户会自动获得 App Clip 体验，Android 用户会自动获得 Fluz 应用深链。platform 仅影响当 URL 在非 iOS 或 Android 设备（例如桌面浏览器）上打开时的行为。

值	桌面 / 未知设备回退行为
`IOS`（默认）	Apple App Clip 启动器
`ANDROID`	Fluz Android 深链
`OTHER`	Fluz Web 应用

选择与你预期 URL 打开环境最匹配的值。如不确定，保持 IOS 即可。

输出

字段	类型	说明
`url`	`String!`	需要交付给用户的短链接。精准指向一张卡。
`expiresAt`	`String!`	ISO-8601 时间戳。URL 在此时间点后失效（≈ 创建后 5 分钟）。

示例

请求

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ virtualCardId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-4333-8444-555555555555" }
  }'

或改为按 offer 选择：

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "66666666-7777-4888-9999-000000000000" }
  }'

响应

{
  "data": {
    "getCardProvisioningUrl": {
      "url": "https://fluz.app.link/abc123XYZ",
      "expiresAt": "2026-05-26T17:42:11.000Z"
    }
  }
}

如何交付该 URL

该 URL 是不透明的且不包含卡号，但它是一个持有者机密：谁打开它，谁就能把那张卡添加到他们的钱包中。请通过你信任的渠道传递给持卡人。常见方式：

屏幕上的二维码 — 用 url 生成二维码并展示；用户用手机相机扫码。
短信 / 电子邮件 — 将链接直接发送到用户的手机或收件箱。
应用内深链 — 在你的移动应用中配置一个按钮，点击后打开 url。

无论采用哪种交付渠道，用户必须在移动设备上打开该 URL——钱包开通流程在那上面进行。

有效期与重新发放

每次调用都会返回一个全新的、指向某一张卡的 URL。
该 URL 在 expiresAt 前有效（≈ 5 分钟）。
打开该 URL 并不会立即使其失效。它在首次使用后会在一个短暂的宽限窗口内保持可兑换，因此务必将其视为持有者机密：通过私密渠道传递，不要记录或缓存。
如果用户未在有效期内操作，只需再次调用 getCardProvisioningUrl 以生成新的链接。不存在单独的“刷新”端点。
要为多张卡开通，请针对每张卡使用其 virtualCardId 分别调用一次查询。

错误处理

所有错误都以标准的 Fluz GraphQL 错误结构返回，错误名称位于 extensions.code 中。

代码	含义	处理方式
`Arguments.INVALID`	ID 不是有效的 UUID，或你同时提供了两个选择器，或都未提供。	仅发送 `virtualCardId` 与 `offerId` 中的一个。
`VirtualCard.CARD_NOT_FOUND`	调用者账户下不存在该卡。	确认 `virtualCardId` 且其归属该账户。
`VirtualCard.CARD_NOT_ACTIVE`	卡存在但不是 `ACTIVE`。	不要重试；该状态下无法添加到钱包。
`VirtualCard.AMBIGUOUS_CARD_SELECTION`	账户在你提供的 `offerId` 上持有多于一张活跃卡。	使用 `virtualCardId` 重试。
`VirtualCard.OFFER_NOT_FOUND`	该卡的 offer 不存在或未激活。	确认 offer id；必要时创建新 offer。
`VirtualCard.OFFER_NOT_ACCESSIBLE`	用户账户不符合该 offer 的资格（活动访问限制）。	向用户展示通用的“不可用”消息。
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	该 offer 的卡计划不支持钱包开通。	对该卡计划不要提供“添加到钱包”。
`Auth.USER_REVOKED_DEVELOPER_ACCESS`	用户已撤销对你应用的 OAuth 访问。	引导用户重新完成 OAuth 授权。
`Auth.INVALID_SCOPE`	令牌不具备 `CREATE_VIRTUALCARD`。	在 OAuth 时请求该 scope。
`Generic.EXTERNAL_SERVICE_ERROR`	下游临时性问题。	重试——该调用可安全重复。

常见问题

该 URL 是否包含卡号？

不包含。该 URL 仅携带短期有效的不透明查找 ID。用户在设备上打开链接后，凭证会被安全地交换。

同一个 URL 能否重复使用？

将其视为一次性使用：每次需要触发流程时都应生成新的链接。打开链接不会立刻使其失效，它会在短暂的宽限期内仍可兑换。请私密投递，且不要记录或缓存。

一个 URL 能否添加多张卡？

不能。每个 URL 精准指向一张卡。请针对每张卡调用一次查询，并传入该卡的 virtualCardId。

如果用户在桌面端怎么办？

他们会落在你用 platform 选择的回退页面（App Clip 启动器、Android 深链或 Fluz Web 应用）。要完成钱包开通，最终仍需在移动设备上打开该 URL。

iOS 和 Android 是否需要区别处理？

不需要。同一个 URL 适用于两者——Fluz 会按设备自动路由。

后续步骤

发送卡片

通过电子邮件、短信或分享链接分发虚拟卡。

设置虚拟卡 PIN

在到店且会提示输入 PIN 的交易前，为符合条件的卡设置 PIN。

​何时使用

​查询

​输入

​ProvisioningPlatform

​输出

​示例

​请求

​响应

​如何交付该 URL

​有效期与重新发放

​错误处理

​常见问题

​后续步骤

发送卡片

设置虚拟卡 PIN

何时使用

查询

输入

`ProvisioningPlatform`

输出

示例

请求

响应

如何交付该 URL

有效期与重新发放

错误处理

常见问题

后续步骤