將卡片寄給他人

本快速入門將帶你完成整個「寄送卡片」生命週期。你將建立一個 Staging 應用程式、鑄造具範圍的 Bearer 權杖、選擇卡片方案、擷取已入金的消費帳戶、產生受託管的虛擬卡連結、體驗收件人啟用流程、驗證發卡，最後停用未使用的連結。到最後你將成功完成所有公開的「寄送卡片」操作：

generateVCShareLinks
getVCShareLinks
deactivateVCShareLinks

—全部都在沙盒中進行，且不會移轉任何真實客戶資金。

先決條件

一個 Fluz 帳號 — 你將在下方步驟 1–2 中建立 Staging API 認證並鑄造具範圍的存取權杖。
請將請求送至沙盒 GraphQL 端點。受託管的收件人連結使用標準的 Fluz 啟用體驗，但所有 API 操作都使用你的 Staging 環境。
你的帳號必須已 啟用寄送卡片（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）驗證以鑄造權杖。

完整流程

建立 Staging 應用程式

建立一個 Fluz 帳號，接著開啟 Developer Console 並建立一個 Staging 應用程式。應用程式建立後，你會收到：

API Key
User ID
Account ID

將以上三個值妥善保存。若你尚未建立 Staging 應用程式，請參閱準備你的帳戶。

以你的認證交換具範圍的 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

受託管的虛擬卡將由你的某個 Spend Account 資助。與一般虛擬卡不同，在產生連結時不會預留任何資金。相反地，只有在收件人成功領取卡片時，所選的 Spend Account 才會被扣款。擷取你可用的 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。你將在產生受託管卡連結時提供此值。

所選的 Spend Account 必須屬於你的帳號，且在收件人領取卡片時必須有足夠資金可用。若在領取當下可用餘額不足，發卡將失敗。

選擇卡片方案

每張受託管卡片都會依據一個虛擬卡**方案（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 狀態開始。

只有在收件人領取連結時，所選的 Spend Account 才會被扣款。在本快速入門中，我們將產生兩個連結：

連結 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

必填

為每張產生卡片提供資金的 Spend Account。儘管此欄位在 GraphQL 結構中看似選填，但實務上為必填。

Int

收件人可用來領取受託管連結的期間。若省略，則使用方案預設值。產生的到期日也會成為已發卡片的鎖定日期。

改以電子郵件或簡訊寄送卡片

若你不想自行分發受託管 URL，Fluz 可替每位收件人傳送其專屬啟用連結。

Email

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

SMS

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

收件人清單長度必須與 quantity 完全相等。若不相符，驗證將失敗且不會建立任何連結。手機號碼必須：

包含國碼
不含空白
以字串提供

範例：

+18883606660

產生受託管連結不會預留資金。若在收件人領取卡片時，所選 Spend Account 的可用餘額不足，發卡將失敗。

產生連結的回應刻意只回傳受託管 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 才會：

發行虛擬卡
從你的 Spend Account 入金
指派給該收件人

收件人成為該卡片的授權持有人。他們不會獲得以下存取權：

你的 Fluz 帳號
你的 Spend Account
你的餘額
任何其他已產生的卡片

發卡後，收件人可以：

檢視卡片
線上消費
將卡片加入 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

大功告成 🎉

你已完成完整的受託管「寄送卡片」生命週期——從產生連結、收件人啟用、生命週期追蹤，到連結撤銷。在此過程中你已：

產生受託管虛擬卡連結。
選擇為收件人卡片提供資金的 Spend Account。
擷取並追蹤分享請求紀錄。
以收件人身分領取受託管卡片。
驗證從 PENDING 到 ISSUED 的轉換。
撤銷未使用的受託管連結。
確認最終的 EXPIRED 狀態。

接下來你可以探索更進階的「寄送卡片」工作流程。

寄送卡片總覽

收件人體驗、方案規則、生命週期狀態，以及完整錯誤參考。

產生分享連結

每個「寄送卡片」操作的詳細 API 參考。

取得 Spend Account

擷取並管理用於資助受託管卡片的 Spend Account。

管理虛擬卡

在卡片發給收件人後進行鎖定與管理。

想了解更多？聯絡我們：support@fluz.app，與專家交流或申請示範。

快速開始

Fluz 控制台

快速入門

將卡片寄給他人

開始之前

完整流程

認識產生設定

Email

SMS

大功告成 🎉

寄送卡片總覽

產生分享連結

取得 Spend Account

管理虛擬卡

​開始之前

​完整流程

​認識產生設定

​Email

​SMS

​大功告成 🎉

寄送卡片總覽

產生分享連結

取得 Spend Account

管理虛擬卡

開始之前

完整流程

認識產生設定

Email

SMS

大功告成 🎉