數位錢包即時加入（Push Provisioning）

使用 getCardProvisioningUrl 查詢來鑄造一個短效期的 URL——當在終端使用者的手機上開啟時——會在該裝置上啟動 Fluz，並將指定的虛擬卡加入 Apple Pay（iOS）或 Google Pay（Android）。你可以用任何方式傳遞此 URL：QR 碼、SMS、電子郵件，或應用內按鈕。接下來的錢包加入流程由 Fluz 處理。

何時使用

凡是你通常會把虛擬卡交給使用者，並希望他們能在手機錢包中一鍵加入、而不需輸入卡號的情境。典型流程：

在為使用者建立卡片 offer 之後，於畫面上顯示 QR 碼。
以簡訊或電子郵件將 URL 傳送給持卡人。
在你自有的行動應用中嵌入「加入 Apple Pay / Google Pay」按鈕。

先決條件： 具備包含 CREATE_VIRTUALCARD scope 的終端使用者 OAuth 存取權杖，以及用來選擇卡片的辨識方式。可以是 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。必須為啟用狀態、符合代碼化（tokenization）資格，且使用者帳戶可存取。僅在帳戶於該 offer 上至多持有一張有效卡時可解析。
`platform`	`ProvisioningPlatform`	否	關於使用者將在哪裡開啟 URL 的提示。預設為 `IOS`。見下方——這並不會將 URL 鎖定於單一平台。

一個 offer 在同一帳戶下可對應多張卡片。一旦某個 offer 上有超過一張有效卡片，offerId 就無法唯一識別單一卡片，查詢會以 VirtualCard.AMBIGUOUS_CARD_SELECTION 失敗，而不會幫你任選其一。若你在同一 offer 上發行多張卡，請使用 virtualCardId。

`ProvisioningPlatform`

回傳的 URL 具備平台感知能力：iOS 使用者會自動獲得 App Clip 體驗，Android 使用者會自動獲得 Fluz 應用的深層連結。platform 僅影響在 iOS 或 Android 裝置以外（例如桌面瀏覽器）開啟 URL 時的行為。

值	桌面／未知裝置的後備行為
`IOS`（預設）	Apple App Clip 啟動器
`ANDROID`	Fluz Android 深層連結
`OTHER`	Fluz 網頁應用

選擇最符合你預期開啟位置的值。如不確定，維持 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 為不透明字串且不包含卡號，但它是持有者即擁有使用權的敏感資訊：任何取得並開啟它的人都能將該卡加入其錢包。請透過你信任的管道傳給持卡人。常見作法：

螢幕上的 QR 碼 — 以 url 產生 QR 並顯示；使用者以手機相機掃描。
SMS／電子郵件 — 直接將連結傳送到使用者的手機或收件匣。
應用內深層連結 — 在你的行動應用中配置按鈕以開啟 url。

無論使用何種傳遞管道，使用者必須在行動裝置上開啟該 URL——錢包加入流程會在那裡進行。

生命週期與重新發行

每次呼叫都會回傳一組「全新」且只對應單一卡片的 URL。
該 URL 於 expiresAt 前有效（約 5 分鐘）。
開啟 URL 不會立即使其失效。它在首次使用後仍會在短暫寬限期內可兌換，因此務必視為敏感資訊：請透過私密通道傳遞，且不要記錄或快取。
若使用者未能及時操作，只需再次呼叫 getCardProvisioningUrl 以鑄造新的 URL。無需另行「refresh」端點。
若要為多張卡加入，請以各自的 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 網頁應用）。要完成錢包加入，仍需要最終在行動裝置上開啟該 URL。

iOS 與 Android 需要做不同處理嗎？

不需要。同一個 URL 對兩者都適用——Fluz 會依裝置自動導流。

後續步驟

傳送卡片

以電子郵件、SMS 或分享連結發送虛擬卡給收件人。

設定虛擬卡 PIN

在可用的卡片上預先設定 PIN，以便於實體交易需要輸入 PIN 時使用。

​何時使用

​查詢

​輸入

​ProvisioningPlatform

​輸出

​範例

​請求

​回應

​如何傳遞 URL

​生命週期與重新發行

​錯誤處理

​常見問題

​後續步驟

傳送卡片

設定虛擬卡 PIN

何時使用

查詢

輸入

`ProvisioningPlatform`

輸出

範例

請求

回應

如何傳遞 URL

生命週期與重新發行

錯誤處理

常見問題

後續步驟