您的第一筆禮品卡購買

本快速入門會帶你從全新的 Fluz 帳戶一路完成一筆測試環境的購買。你將註冊一個應用程式、鑄造具範圍的存取權杖，接著存入資金、瀏覽商家目錄、購買禮品卡，並揭露其兌換細節——全都在沙盒環境中完成，不會有任何真實金錢流動。

先決條件

一個 Fluz 帳戶——你將在以下步驟 1–2 建立測試環境 API 憑證並鑄造存取權杖。
請將請求送往沙盒 GraphQL 端點。這裡不會對真實卡片進行請款——請見 Staging vs. Live Environment。
每個 mutation 都需要唯一的 idempotencyKey（由客戶端產生的 UUID），以確保請求只會被處理一次——請見 Idempotency。

開始之前

每個呼叫都是對單一 GraphQL 端點的 POST 請求。鑄造你的權杖（步驟 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 getWallet { getWallet { bankCards { bankCardId lastFourDigits } } }"
  }'

你的沙盒帳戶隨附一張預先加入的測試銀行卡，因此你可以立刻執行整個流程。你也可以在 Sandbox Accounts page 新增更多測試信用卡或銀行帳戶，使用 Test Bank Cards 清單中的測試資料。

完整流程

註冊並建立應用程式

先在 fluz.app 建立 Fluz 帳戶，接著開啟 Developer Console 並建立新的 Staging 應用程式。當憑證顯示後，請複製你的 API Key、User ID 和 Account ID。完整教學：準備你的帳戶。

以憑證交換存取權杖

使用你的 API Key 鑄造一個短效、具範圍的使用者存取權杖。此呼叫送往相同的 GraphQL 端點，並以 Authorization: Basic <YOUR_API_KEY> 驗證；其後所有呼叫都改以回傳的權杖作為 Bearer 憑證。

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": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'

{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }
}

儲存回傳的 token，並在下方每個請求都以 Authorization: Bearer <token> 送出。權杖為短效——請在伺服器端鑄造，權杖過期時以相同的 mutation 鑄造新權杖（見 Refresh an expired access token）。完整細節：API credentials。

權杖的 scopes 決定能執行的動作——僅包含你的流程需要的範圍即可：MANAGE_PAYMENT 用於新增資金來源與存款，LIST_OFFERS 用於瀏覽目錄，PURCHASE_GIFTCARD / REVEAL_GIFTCARD 用於購買與揭露。

請勿在瀏覽器或行動端客戶端暴露你的 API Key。請在伺服器端鑄造權杖，並只將權杖轉發給客戶端。

將資金存入你的 Fluz 餘額

預先儲值 Fluz 餘額通常能加快禮品卡購買，也可略過某些速度限制檢查。你可以用兩種方式存入：

手動，透過沙盒版 Fluz 網站。
程式化，透過 depositCashBalance mutation（如下所示）。

首先，擷取付款方式 ID（getWallet）

若要透過 API 存入，你需要資金來源（例如 bankCardId）的 ID。執行 getWallet 並保存你要使用的 ID。

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 getWallet { getWallet { bankCards { bankCardId lastFourDigits } bankAccounts { bankAccountId } } }"
  }'

從回應中取得 bankCardId 或 bankAccountId。透過 API 管理資金來源需要 MANAGE_PAYMENT scope。更多細節：View Funding Sources。

進行存款

使用 depositCashBalance mutation。它接受一個 DepositCashBalanceInput 物件。

mutation depositCashBalance($input: DepositCashBalanceInput!) {
  depositCashBalance(input: $input) {
    cashBalanceDeposits {
      cashBalanceDepositId
      depositDisplayId
      depositAmount
      status
      cashBalanceDepositType
    }
    balances {
      cashBalance { availableBalance totalBalance pendingBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance }
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "amount": 100.00,
    "depositType": "CASH_BALANCE",
    "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19"
  }
}

輸入欄位

string

必填

由客戶端產生的唯一 UUID，保證此存款只會被處理一次。

Float

必填

要存入的金額。

CashBalanceDepositType

目的餘額。可為 CASH_BALANCE、GIFT_CARD_BALANCE 或 RESERVE_BALANCE。

UUID

資金來源——請提供其一：bankAccountId、bankCardId 或 paypalVaultId。

Int

僅適用於 GIFT_CARD_BALANCE。用於分類商家的四位數 MCC。使用 getMccList 取得有效值。

UUID

當選擇 CASH_BALANCE 時，要存入的特定消費帳戶。

範例回應

{
  "data": {
    "depositCashBalance": {
      "cashBalanceDeposits": [
        {
          "cashBalanceDepositId": "5f5c5b5f-4c4b-4e4e-9e9e-4f4f4f4f4f4f",
          "depositDisplayId": "102370",
          "depositAmount": "100.00",
          "status": "COMPLETED",
          "cashBalanceDepositType": "CASH_BALANCE"
        }
      ],
      "balances": {
        "cashBalance": {
          "availableBalance": "100.00",
          "totalBalance": "100.00",
          "pendingBalance": "0.00"
        },
        "giftCardCashBalance": {
          "availableBalance": "0.00",
          "totalBalance": "0.00",
          "pendingBalance": "0.00"
        }
      }
    }
  }
}

根據資金來源與清算類型不同，存款可能即時入帳，或需 2–5 個工作天。回應中的 balances 物件反映你目前可用餘額。隨時重新查詢請見 Check Account Balance。

瀏覽商家並挑選優惠

餘額就緒後，使用 getMerchants 擷取可用商家及其現金回饋優惠的目錄。

query GetMerchantCatalog(
  $paginate: OffsetInput
  $offerTypes: OfferTypesInput
  $filterBy: FilterByInput
) {
  getMerchants(paginate: $paginate, offerTypes: $offerTypes, filterBy: $filterBy) {
    merchantId
    name
    slug
    logoUrl
    faceplateUrl
    offers {
      offeringMerchantId
      offerId
      type
      deliveryFormat
      barcodeType
      offerRates {
        maxUserRewardValue
        cashbackVoucherRewardValue
        boostRewardValue
        denominations
        allowedPaymentMethods
      }
    }
  }
}

{
  "paginate": { "limit": 20, "offset": 0 },
  "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
}

目錄預設依現金回饋百分比排序，最高的優惠會排在最前面。

實用參數

String

依名稱篩選商家。

OffsetInput

{ limit, offset }。預設與最大 limit 皆為 20。

OfferTypesInput

要回傳哪些優惠類型的布林旗標，例如 { giftCardOffer: true, cardLinkedOffer: false }。

FilterByInput

在每個商家內篩選優惠，例如依 deliveryFormat（URL、CODES、PIN_AS_CODE、PIN_WITH_URL）過濾。

分頁： 回應的結果數可能少於你的 limit。若要拉取完整目錄，請持續以你的 limit 增加 offset，當 API 回傳空陣列（[]）時停止。未過濾的目錄很大——最多一天擷取一次，並使用 name 或 offerTypes 進行目標性查詢。

選配：取得某商家的單一最佳優惠（getOfferQuote）

若你已知道商家與金額，getOfferQuote 能直接回傳當前可用的頂級優惠——包含即時庫存資訊。

query getOfferQuote($input: GetOfferQuoteInput!) {
  getOfferQuote(input: $input) {
    offeringMerchantId
    offerId
    type
    hasStockInfo
    denominationsType
    termsAndConditions
    offerRates {
      maxUserRewardValue
      denominations
      allowedPaymentMethods
    }
    stockInfo {
      ... on StockInfoVariableType {
        __typename
        description
        maxDenomination
        minDenomination
      }
      ... on StockInfoFixedType {
        __typename
        denomination
        availableStock
      }
    }
  }
}

{
  "input": {
    "merchantSlug": "starbucks",
    "denomination": 50.00,
    "paymentMethod": "FLUZPAY"
  }
}

merchantSlug 與 denomination 為必填。paymentMethod 預設為 FLUZPAY（你的 Fluz 餘額），也可接受 BANK_CARD、BANK_ACCOUNT、PAYPAL、APPLE_PAY 和 GOOGLE_PAY。

現金回饋比率會經常變動。購買前請務必確認當前比率。

購買禮品卡

使用 purchaseGiftCard mutation。你可以用兩種方式指定要購買的項目：

選項 A — Merchant slug（建議）
選項 B — 指定 offer ID

傳入 merchantSlug，Fluz 會自動套用該商家最優的可用優惠。

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "merchantSlug": "starbucks",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

傳入你從目錄中選擇的 offerId，以購買該特定優惠。

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

輸入欄位

string

必填

由客戶端產生的唯一 UUID，確保此購買只會被處理一次。

UUID / String

必填

請擇一提供。merchantSlug 會自動選用最佳回饋率；offerId 則鎖定特定優惠。

Float

必填

欲購買的禮品卡金額。

UUID / Float

付款方式。使用 balanceAmount（Fluz 餘額）、bankAccountId、bankCardId 或 paypalVaultId。你可以將 Fluz 餘額與其他來源搭配使用。

Boolean

預設值:"true"

若其他付款方式失敗，則退回使用 Fluz 餘額。若要停用此退回機制，請設為 false。

Float

透過 merchantSlug 購買時可接受的最低回饋率。

UUID

強制使用特定的專屬回饋率。可在 getMerchants 中找到類型為 EXCLUSIVE_RATE_OFFER 的優惠。

UUID

要扣款的消費帳戶（現金餘額）。

String / String / UUID

選用的費用註記。memo 最多 255 字元；分類會在首次使用時建立。請見 Add Expense Details。

範例回應

{
  "data": {
    "purchaseGiftCard": {
      "purchaseDisplayId": "1019688",
      "purchaseAmount": 50.00,
      "giftCard": {
        "giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "status": "ACTIVE",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
      }
    }
  }
}

請保留回應中的 giftCardId——你會在下一步用它來揭露卡片資訊。若購買失敗，請查閱 Gift Card Error Codes。

揭露禮品卡詳細資訊

最後，擷取可兌換的細節（代碼、PIN 和/或 URL）。

沒有 giftCardId？先列出你的卡片（getGiftCards）

若你在步驟 3 剛取得 giftCardId 則可略過。否則，先列出你的禮品卡：

query GetGiftCards {
  getGiftCards(paginate: { limit: 20, offset: 0 }) {
    giftCardId
    status
    createdAt
    deliveryFormat
    termsAndConditions
    merchant { merchantId name slug }
  }
}

你可以用 status 與 userCashBalanceId 進行篩選，並以 paginate 分頁。

揭露兌換細節

使用 giftCardId 呼叫 revealGiftCardByGiftCardId。

mutation RevealGiftCard($giftCardId: UUID!) {
  revealGiftCardByGiftCardId(giftCardId: $giftCardId) {
    code
    pin
    url
    termsAndConditions
  }
}

{
  "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4"
}

範例回應

{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}

兌換欄位會依商家而異。有些卡僅回傳英數字的 code 而無 pin；有些則只回傳 url。請一律依 getGiftCards 回傳的 deliveryFormat 進行畫面呈現（而非 getMerchants）——商家的有效優惠在購買後可能改變，而 getGiftCards 反映的是實際購買時的格式。

沒有即時回傳詳細資訊？ 請用指數退避輪詢 revealGiftCardByGiftCardId：從 300ms 開始，每次加倍（300 → 600 → 1200 → 2400ms…），最大延遲 180000ms（3 分鐘）。一旦取得詳細資訊就停止。這能在回應速度與系統負載之間取得平衡，並避免不必要的逾時。

大功告成 🎉

你已跑完一筆完整交易——儲值餘額、瀏覽優惠、購買禮品卡並揭露卡片資訊。接下來，探索其餘的 API 功能：

Virtual Cards

發行並管理可被網路接受的虛擬卡。

Wallets & Transfers

開立消費帳戶並在其間轉移資金。

Transaction Activity

擷取、篩選並註記交易歷史。

Embedded Widgets

將 Fluz 的流程直接嵌入你的自有介面。

想了解更多？ 歡迎聯絡我們：support@fluz.app 與專家對談或申請示範。

快速開始

Fluz 控制台

快速入門

您的第一筆禮品卡購買

開始之前

完整流程

進行存款

輸入欄位

實用參數

輸入欄位

揭露兌換細節

大功告成 🎉

Virtual Cards

Wallets & Transfers

Transaction Activity

Embedded Widgets

​開始之前

​完整流程

​進行存款

​輸入欄位

​實用參數

​輸入欄位

​揭露兌換細節

​大功告成 🎉

Virtual Cards

Wallets & Transfers

Transaction Activity

Embedded Widgets

開始之前

完整流程

進行存款

輸入欄位

實用參數

輸入欄位

揭露兌換細節

大功告成 🎉