您的第一笔礼品卡购买

本快速入门将带你从一个全新的 Fluz 账户完成一次预发环境中的购买。你将注册一个应用、铸造带作用域的访问令牌，然后充值、浏览商户目录、购买礼品卡，并展示其兑换详情——以上均在沙盒环境中完成，不涉及真实资金流转。

先决条件

一个 Fluz 账户——你将在下面的步骤 1–2 中创建预发 API 凭据并铸造访问令牌。
请求发送到沙盒 GraphQL 端点。此处不会对真实卡片收费——参见预发 vs. 生产环境。
每个变更操作都需要唯一的 idempotencyKey（客户端生成的 UUID），以确保每个请求只被处理一次——参见幂等性。

开始之前

每次调用都是向同一个 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 页面按照测试银行卡列表中的取值添加更多测试卡或银行账户。

全流程

注册并创建应用

在 fluz.app 创建 Fluz 账户，然后打开开发者控制台并创建一个新的 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> 发送。令牌为短期有效——请在服务端铸造它们，并在令牌过期时使用相同的变更再次铸造一个新的（参见刷新已过期的访问令牌）。详情参见：API 凭据。

作用域控制令牌的权限——仅包含你的流程所需的权限：MANAGE_PAYMENT 用于添加资金来源与充值，LIST_OFFERS 用于浏览目录，PURCHASE_GIFTCARD / REVEAL_GIFTCARD 用于购买与展示。

切勿在浏览器或移动端客户端中暴露你的 API Key。请在服务端铸造令牌，并仅向前端转发该令牌。

向你的 Fluz 余额充值

预先向 Fluz 余额充值通常能让礼品卡购买更快，并可能绕过某些速率限制检查。你可以通过两种方式充值：

手动，通过沙盒 Fluz 网站。
以编程方式，通过 depositCashBalance 变更（如下所示）。

首先，获取支付方式 ID（getWallet）

通过 API 进行充值时，你需要一个资金来源的 ID（例如 bankCardId）。运行 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 作用域。更多详情：查看资金来源。

发起充值

使用 depositCashBalance 变更。它接收一个 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 对象反映你当前的可用余额。随时重新查询请参见检查账户余额。

浏览商户并选择一个优惠

余额就绪后，使用 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 的结果。要拉取完整目录，请持续将 offset 以 limit 递增，直到 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 变更。你可以通过两种方式指定购买的内容：

选项 A — 商户 slug（推荐）
选项 B — 指定优惠 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 字符；分类在首次使用时创建。参见添加费用详情。

示例响应

{
  "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——你将在下一步用它来展示礼品卡。如果购买失败，请查看礼品卡错误代码。

展示礼品卡详情

最后，获取可用于兑换的详情（代码、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

开始之前

全流程

发起充值

入参说明

常用参数

入参说明

展示兑换详情

大功告成 🎉