您的第一笔礼品卡购买

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

先决条件

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

开始之前

除铸造令牌（步骤 2）外，其他每次调用都是到同一个 GraphQL 端点的 POST 请求，并使用 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 应用。凭证出现后，复制你的 clientId 和 clientSecret——密钥只显示一次。详细教程：准备你的账户。

用凭证换取访问令牌

使用应用凭证铸造一个短期有效、带作用域的用户访问令牌。此调用请求 OAuth 服务；后续所有调用都使用返回的令牌作为 Bearer 凭证。

curl -X POST https://oauth-service.fluzapp.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($clientId: String!, $clientSecret: String!, $scopes: [Scope!]!) { generateUserAccessToken(clientId: $clientId, clientSecret: $clientSecret, scopes: $scopes) { accessToken expiresIn scopes } }",
    "variables": {
      "clientId": "<APPLICATION_CLIENT_ID>",
      "clientSecret": "<APPLICATION_CLIENT_SECRET>",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'

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

保存返回的 accessToken，并在下方每个请求中以 Authorization: Bearer <accessToken> 发送。令牌短期有效（expiresIn 单位为秒）——请在服务端铸造并在过期前刷新。详情参见：API 凭证。

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

切勿在浏览器或移动端暴露 clientSecret。请在服务端铸造令牌，仅转发令牌。

向你的 Fluz 余额充值

预先充值 Fluz 余额通常能加快礼品卡购买速度，并可绕过某些频控检查。你可以通过两种方式充值：

手动，通过沙盒 Fluz 网站。
编程方式，通过 depositCashBalance mutation（如下）。

首先，获取支付方式 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 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"
  }
}

输入字段

idempotencyKey

string

必填

客户端生成的唯一 UUID，保证充值只被处理一次。

amount

Float

必填

充值金额。

depositType

CashBalanceDepositType

目标余额。可为 CASH_BALANCE、GIFT_CARD_BALANCE 或 RESERVE_BALANCE。

Funding source

UUID

资金来源——提供一个 bankAccountId、bankCardId 或 paypalVaultId。

merchantCategoryCode

Int

仅用于 GIFT_CARD_BALANCE。四位数 MCC 分类码。使用 getMccList 获取有效值。

userCashBalanceId

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 }
}

目录默认按返现百分比排序，最高的优惠会排在最前面。

常用参数

name

String

按名称筛选商户。

paginate

OffsetInput

{ limit, offset }。默认与最大 limit 为 20。

offerTypes

OfferTypesInput

返回何种优惠类型的布尔标志，例如 { giftCardOffer: true, cardLinkedOffer: false }。

filterBy

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": {
    "slug": "starbucks",
    "denomination": 50.00,
    "paymentMethod": "FLUZPAY"
  }
}

slug 与 denomination 为必填。paymentMethod 默认为 FLUZPAY（你的 Fluz 余额），也可为 BANK_CARD、BANK_ACCOUNT、PAYPAL、APPLE_PAY 和 GOOGLE_PAY。

返现比例会定期变动。购买前务必确认当前比例。

购买礼品卡

使用 purchaseGiftCard mutation。你可以通过两种方式指定要购买的内容：

方案 A — 商户 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
  }
}

输入字段

idempotencyKey

string

必填

客户端生成的唯一 UUID，确保购买只被处理一次。

offerId / merchantSlug

UUID / String

必填

二选一。merchantSlug 会自动选择最佳比例；offerId 指定特定优惠。

amount

Float

必填

购买的礼品卡面额。

Funding source

UUID / Float

支付方式。使用 balanceAmount（Fluz 余额）、bankAccountId、bankCardId 或 paypalVaultId。你可以将 Fluz 余额与其他来源组合支付。

defaultToBalance

Boolean

默认值:"true"

当其他支付方式失败时回退到 Fluz 余额。设为 false 可禁用回退。

minRewardRate

Float

使用 merchantSlug 购买时可接受的最低奖励比例。

exclusiveRateId

UUID

强制使用特定的专属比例。在 getMerchants 中可找到类型为 EXCLUSIVE_RATE_OFFER 的优惠对应的值。

userCashBalanceId

UUID

要扣款的消费账户（现金余额）。

memo / transactionCategory / attachmentId

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

开始之前

完整流程

发起充值

输入字段

常用参数

输入字段

揭示兑换详情

大功告成 🎉