數位錢包推送式佈建（Push Provisioning）

使用 getCardProvisioningUrl 查詢來產生一個短效、一次性使用的 URL。當終端使用者在手機上開啟該連結時，會在該裝置上啟動 Fluz，並將指定優惠的虛擬卡新增至 Apple Pay（iOS）或 Google Pay（Android）。你可以用任何方式傳遞此 URL：QR code、SMS、電子郵件，或應用程式內按鈕。之後 Fluz 會接手並完成錢包佈建流程。

何時使用

在任何你通常會提供虛擬卡給使用者，且希望他們能在手機錢包中一鍵加入、而不需輸入卡號的情境。常見流程：

建立卡片優惠後，於畫面上顯示 QR code。
以簡訊或電子郵件將 URL 傳給持卡人。
在你自家的行動應用程式中嵌入「加入 Apple Pay / Google Pay」按鈕。

先決條件： 擁有包含 CREATE_VIRTUALCARD 權限範圍的終端使用者 OAuth 存取權杖，以及該使用者的虛擬卡優惠（透過既有的 offer API 建立）。

此查詢不接受基本驗證（client_id / client_secret）— 必須使用使用者情境的 Bearer 權杖。

查詢

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

輸入

欄位	型別	必填	說明
`offerId`	`String!` (UUIDv4)	yes	要進行佈建的虛擬卡優惠。必須為啟用中、可代幣化，且可由該使用者帳戶存取。
`platform`	`ProvisioningPlatform`	no	對使用者將在哪裡開啟 URL 的提示。預設為 `IOS`。見下方 — 這並不會將 URL 鎖定於單一平台。

`ProvisioningPlatform`

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

值	桌面 / 未知裝置的後援行為
`IOS` (default)	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:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-3333-4444-555555555555" }
  }'

回應

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

如何傳遞 URL

此 URL 為不透明且不包含敏感資料 — 可安全地以 QR code、SMS、電子郵件或應用程式內 UI 呈現。常見做法：

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

無論使用何種傳遞管道，使用者必須在行動裝置上開啟 URL — 錢包佈建會在該處進行。

有效期間與重新發行

每次呼叫都會回傳一個「全新、一次性」的 URL。
URL 有效至 expiresAt（約 5 分鐘）。
若使用者未及時操作，只需再次呼叫 getCardProvisioningUrl 以產生新的連結。沒有獨立的「refresh」端點。

錯誤處理

所有錯誤均以標準 Fluz GraphQL 錯誤格式回傳，錯誤名稱位於 extensions.code。

代碼	意義	處置方式
`Arguments.INVALID`	`offerId` 不是有效的 UUID。	在你方先行驗證輸入。
`VirtualCard.OFFER_NOT_FOUND`	優惠不存在或未啟用。	確認優惠 ID；必要時建立新優惠。
`VirtualCard.OFFER_NOT_ACCESSIBLE`	使用者帳戶不符合此優惠（行銷活動存取）。	呈現一般性的「無法使用」訊息。
`VirtualCard.OFFER_NOT_AVAILABLE`	該優惠已兌換成卡片且該卡片已不再有效。	不要用相同優惠重試；請建立新的優惠。
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	此優惠的卡片計畫不支援錢包佈建。	不要為此卡片計畫提供「加入錢包」。
`Auth.USER_REVOKED_DEVELOPER_ACCESS`	使用者已撤銷你應用的 OAuth 存取。	讓使用者重新進行 OAuth 同意。
`Auth.INVALID_SCOPE`	權杖不含 `CREATE_VIRTUALCARD`。	在 OAuth 流程中請求該範圍。
`Generic.EXTERNAL_SERVICE_ERROR`	下游暫時性問題。	重試 — 此呼叫可安全重複。

常見問題

此 URL 是否包含卡號？

不會。該 URL 只攜帶短效的不透明查詢 ID。當使用者開啟連結後，裝置上才會安全地交換憑證。

同一個 URL 可以重複使用嗎？

不行。它為一次性使用。每次需要啟動該流程時都要產生新連結。

如果使用者在桌面端怎麼辦？

他們會根據你在 platform 所選的後援行為抵達（App Clip 啟動器、Android 深層連結，或 Fluz 網頁應用）。要完成錢包佈建，最終仍需在行動裝置上開啟 URL。

iOS 與 Android 需要做不一樣的處理嗎？

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

後續步驟

發送卡片

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

設定虛擬卡 PIN

在面對面且需要輸入 PIN 的交易前，為符合條件的卡片設定 PIN。

​何時使用

​查詢

​輸入

​ProvisioningPlatform

​輸出

​範例

​請求

​回應

​如何傳遞 URL

​有效期間與重新發行

​錯誤處理

​常見問題

​後續步驟

發送卡片

設定虛擬卡 PIN

何時使用

查詢

輸入

`ProvisioningPlatform`

輸出

範例

請求

回應

如何傳遞 URL

有效期間與重新發行

錯誤處理

常見問題

後續步驟