取得被拒絕的交易

Overview

被拒絕交易 API 可讓你擷取與你的帳戶相關、被拒絕/失敗的所有金融交易之完整歷史。包含購買、存款、提領、轉帳、帳單支付，以及所有其他金融活動。 端點類型: GraphQL Query
驗證: 需要（JWT Bearer Token）
速率限制: 適用標準 GraphQL 速率限制

需要授權此 mutation 需要 LIST_PAYMENT 與 LIST_PURCHASES 權限範圍。在嘗試取得被拒絕交易清單之前，請確保你的存取權杖已被授予這些權限範圍。

Declined Transaction

DeclineTransaction 物件包含資訊。以下是表格：

Field name	Type	Description
`transactionId`	`UUID!`	被拒絕交易的唯一識別碼
`transactionType`	`String!`	被拒絕的交易類型（例如：「Gift Card Purchase」、「Virtual Card Purchase」、「Add Money」、「Withdrawal」、「Transfer - Out」、「Bill Payment Initiation」、「Issue Virtual Card」）
`amount`	`Float!`	嘗試之交易的總金額，使用交易的幣別
`fluzAmount`	`Float!`	由 Fluz 內部餘額（現金/獎勵/保留/預付款）資助的部分。不適用時預設為 0
`externalFundingAmount`	`Float!`	由外部來源（例如連結的銀行/卡片）資助的部分。不適用時預設為 0
`currency`	`String!`	ISO 4217 貨幣代碼。未指定時預設為「USD」
`sourceRecordType`	`String`	來源記錄的類型（例如來源網域/實體類型）
`sourceRecordId`	`String`	來源記錄的識別碼
`accountId`	`String!`	擁有該筆交易的 Fluz 帳戶識別碼
`userId`	`String`	嘗試進行該交易的使用者識別碼。對於帳戶層級/系統交易可能不存在
`source`	`String`	資金來源/起源標籤（例如資金來源或發起方）
`destination`	`String`	目的地標籤（例如商家或收款人）。對於商家交易通常為商家
`status`	`DeclinedTransactionStatus!`	結果狀態：`DECLINED` 或 `FAILED`
`merchantId`	`String`	已知時，相關商家的識別碼
`descriptorId`	`String`	用於強化商家中介資料的已解析商家描述子識別碼
`liabilityId`	`String`	適用時，相關負債記錄的識別碼
`merchantName`	`String`	商家的顯示名稱。當識別出商家時，會從 destination 填入
`merchantCountry`	`String`	商家所在國家
`merchantCity`	`String`	商家所在城市
`merchantState`	`String`	商家所在州/地區
`logoUrl`	`String`	要顯示的標誌 URL（通常是商家/品牌標誌）
`category`	`String`	交易或商家的分類/歸類
`cardLastFour`	`String`	使用之卡片的後四碼
`cardDisplayName`	`String`	使用之卡片的人性化顯示名稱
`virtualCardId`	`String`	適用時，所涉虛擬卡的識別碼
`channel`	`String`	啟動該交易的管道（例如 app、web、integration）
`externalFundingSourceType`	`String`	使用的外部資金來源類型（例如銀行帳戶、扣款卡）
`externalFundingSourceId`	`String`	使用的外部資金來源識別碼
`fundingSourceSubtype`	`String`	資金來源子類型（例如支票/儲蓄，或卡網子類型）
`isCashBalanceUsed`	`Boolean!`	若使用者的現金餘額已被套用/嘗試，則為 True
`isPrepaymentBalanceUsed`	`Boolean!`	若禮品卡預付款餘額已被套用/嘗試，則為 True
`isRewardsBalanceUsed`	`Boolean!`	若獎勵餘額已被套用/嘗試，則為 True
`isReserveBalanceUsed`	`Boolean!`	若保留餘額已被套用/嘗試，則為 True
`transactionDateTime`	`String!`	交易的時間戳，為 ISO 8601 字串（源自建立時間）
`spendAccountNickname`	`String`	使用之消費帳戶的暱稱。未設定時回退為「Main account」
`declineTitle`	`String`	面向使用者的簡短標題，摘要說明拒絕原因
`declineReason`	`String`	面向使用者的原因，說明為何交易被拒
`declineDescription`	`String`	面向使用者的較長描述，提供更多拒絕細節
`declineCtaText`	`String`	引導使用者下一步動作的行動呼籲文字
`declineCategory`	`String`	拒絕的分類（用於分組/導向拒絕訊息）
`offerId`	`UUID`	適用時，相關優惠的識別碼
`issuer`	`String`	與卡片/交易相關的發卡機構
`bin`	`String`	卡片的銀行識別碼（前幾碼）
`limitAmount`	`String`	與此次拒絕相關的消費限額金額（例如超出之限額）
`limitDuration`	`String`	消費限額適用的期間/窗口（例如單筆、每日、每月）
`lockOnNextUse`	`String`	指示卡片是否設定為下次使用時鎖定
`lockDate`	`String`	與卡片鎖定相關的日期（適用時）
`bankAccountNickname`	`String`	與資金來源關聯之銀行帳戶暱稱
`bankAccountLastFour`	`String`	與資金來源關聯之銀行帳戶後四碼
`isPrivate`	`Boolean`	隱私旗標，指示是否應將該交易視為私密
`createdAt`	`DateTime!`	建立該交易記錄的時間戳
`updatedAt`	`DateTime!`	該交易記錄最後更新的時間戳

Quick Start

要取得與你的帳戶相關的被拒絕交易清單，請使用 getDeclinedTransactions 查詢。此呼叫會回傳被拒絕交易的詳細清單，包括 transactionId、amount、status 與 destination。

Variables

Field	Type	Required	Description
`filter`	`UserCashBalanceFilterInput`	No	針對消費帳戶的篩選條件
`paginate`	`OffsetInput`	No	分頁參數（預設：limit=20, offset=0）

Sample Request

query GetDeclinedTransactions(
  $filter: DeclinedTransactionFilterInput
  $paginate: OffsetInput
) {
  getDeclinedTransactions(filter: $filter, paginate: $paginate) {
    totalCount
    hasNextPage
    transactions {
      transactionId
      transactionType
      amount
      fluzAmount
      externalFundingAmount
      currency
      status
      accountId
      userId
      source
      destination
      merchantId
      merchantName
      merchantCity
      merchantState
      merchantCountry
      logoUrl
      category
      cardLastFour
      cardDisplayName
      virtualCardId
      declineTitle
      declineReason
      declineDescription
      declineCtaText
      declineCategory
      isCashBalanceUsed
      isPrepaymentBalanceUsed
      isRewardsBalanceUsed
      isReserveBalanceUsed
      externalFundingSourceType
      externalFundingSourceId
      fundingSourceSubtype
      bankAccountNickname
      bankAccountLastFour
      channel
      offerId
      issuer
      bin
      limitAmount
      limitDuration
      lockOnNextUse
      lockDate
      isPrivate
      createdAt
      updatedAt
    }
  }
}

請注意，因速率限制，你可能需要進行分頁並多次呼叫被拒絕交易清單。

Sample Response

回應將包含被拒絕交易的清單

{
  "data": {
    "getDeclinedTransactions": {
      "totalCount": 1,
      "hasNextPage": false,
      "transactions": [
        {
          "transactionId": "237b8450-7d2c-4233-9227-420bd7ed569d",
          "transactionType": "Virtual Card Purchase",
          "amount": 125.00,
          "fluzAmount": 0.00,
          "externalFundingAmount": 0.00,
          "currency": "USD",
          "status": "DECLINED",
          "accountId": "58c46f99-472f-4c5b-a4b5-776fa757263a",
          "userId": "23dff16a-773f-4c5d-accf-a61e70f1afa7",
          "source": "ACH Plaid Silver Standard 0.1% Interest Saving 1111",
          "destination": "Uber",
          "sourceRecordType": "VIRTUAL_CARD_TRANSACTION_ACTIVITY",
          "sourceRecordId": "3b6e6b77-d720-4679-8461-919e0b28df00",
          "merchantId": "9f83fa82-435e-4553-9525-8c7871825f74",
          "descriptorId": "2f30bea0-33a9-4b4b-95ce-b19662821d45",
          "liabilityId": null,
          "merchantName": "Uber",
          "merchantCountry": "USA",
          "merchantCity": null,
          "merchantState": null,
          "logoUrl": "https://storage.googleapis.com/fluz-fluz-file-uploads-prod-ricuyxowbwlfprel/UBER-logo.jpg",
          "category": "Miscellaneous Specialty Retail",
          "cardLastFour": "3258",
          "cardDisplayName": null,
          "virtualCardId": "73b9708a-92e4-45d5-930c-ae24e4997f91",
          "channel": null,
          "externalFundingSourceType": "BANK_ACCOUNT",
          "externalFundingSourceId": "7bc2c9ad-fd58-4be1-b782-284c59f54900",
          "fundingSourceSubtype": "SAVING",
          "isCashBalanceUsed": true,
          "isPrepaymentBalanceUsed": true,
          "isRewardsBalanceUsed": true,
          "isReserveBalanceUsed": false,
          "transactionDateTime": "2026-06-23T15:44:33.928Z",
          "spendAccountNickname": "Main account",
          "declineTitle": "Insufficient funds",
          "declineReason": "There aren't enough funds available on this card. Would you like to add funds?",
          "declineDescription": "Your $125.00 transaction was declined because your funding source has insufficient funds.",
          "declineCtaText": "Add money",
          "declineCategory": "Virtual Card",
          "offerId": null,
          "issuer": null,
          "bin": null,
          "limitAmount": null,
          "limitDuration": null,
          "lockOnNextUse": null,
          "lockDate": null,
          "bankAccountNickname": "ACH Plaid Silver Standard 0.1% Interest Saving",
          "bankAccountLastFour": "1111",
          "isPrivate": false,
          "createdAt": "2026-06-23T15:44:33.928Z",
          "updatedAt": "2026-06-23T15:44:41.205Z"
        }
      ]
    }
  }
}

Field	Type	Description
`transactionId`	`[UUID]`	依特定交易記錄 ID 篩選
`status`	`[DeclinedTransactionStatus]`	依狀態篩選（`DECLINED` 或 `FAILED`）。省略時預設為兩者皆包含
`amount`	`Float`	依確切金額篩選
`amountGte`	`Float`	依最小金額（大於或等於）篩選
`amountLte`	`Float`	依最大金額（小於或等於）篩選
`fluzAmount`	`Float`	依確切 Fluz 金額篩選
`fluzAmountGte`	`Float`	依最小 Fluz 金額（大於或等於）篩選
`fluzAmountLte`	`Float`	依最大 Fluz 金額（小於或等於）篩選
`createdGte`	`DateTime`	依建立日期（大於或等於）篩選
`createdLte`	`DateTime`	依建立日期（小於或等於）篩選
`updatedGte`	`DateTime`	依最後更新日期（大於或等於）篩選
`updatedLte`	`DateTime`	依最後更新日期（小於或等於）篩選
`merchantId`	`[UUID]`	依商家 ID 篩選
`merchant`	`[String]`	依商家名稱篩選（比對 `destination` 欄位）
`transactionType`	`[String]`	依交易類型篩選（例如 `"Gift Card Purchase"`、`"Virtual Card Purchase"`）
`channel`	`[String!]`	依管道篩選（例如 `"UWP"`、`"app"`）
`category`	`[String]`	依交易或商家分類篩選
`virtualCardId`	`[UUID]`	依特定虛擬卡 ID 篩選
`fundingSource`	`[String]`	依資金來源名稱篩選
`userCashBalanceId`	`[UUID]`	依消費帳戶 ID 篩選
`liabilityId`	`UUID`	依負債 ID 篩選（用於帳單支付交易）

範例 - 僅取得 DECLINED 的消費帳戶

{
	"filter": {
  	"status": [DECLINED]
  }
}

Pagination

Field	Type	Default	Max	Description
`limit`	`Int`	20	20	每頁要回傳的交易數量
`offset`	`Int`	0	-	要略過的交易數量

範例 - 第 1 頁：

{
	"paginate": {
  	"limit": 20,
  	"offset": 0
  }
}

範例 - 第 2 頁：

{
	"paginate": {
  	"limit": 20,
  	"offset": 20,
	}
}

Best Practices

1. 有效使用分頁

總是檢查 hasNextPage 以判斷是否仍有更多結果：

async function fetchDeclinedTransactions() {
  const transactions = [];
  let offset = 0;
  const limit = 20;
  
  while (true) {
    const result = await getDeclinedTransactions({ 
      paginate: { limit, offset } 
    });
    
    transactions.push(...result.transactions);
    
    if (!result.hasNextPage) break;
    offset += limit;
  }
  
  return transactions;
}

2. 只請求所需欄位

僅指定你需要的欄位以減少回應大小：

# ✅ Good - minimal fields
getDeclinedTransactions {
  transactions {
    transactionId
    transactionType
    amount
    createdAt
  }
  totalCount
  hasNextPage
}

# ❌ Less efficient - requesting all 40+ fields
getDeclinedTransactions {
  transactions {
    transactionId
    transactionType
    amount
    ... (all fields)
  }
}

3. 針對歷史查詢使用日期篩選

查詢較早期的交易時，務必使用日期篩選：

# ✅ Good
filter: {
  createdGte: "2024-01-01T00:00:00Z"
  createdLte: "2024-12-31T23:59:59Z"
}

5. 有效率地組合篩選條件

先使用範圍篩選縮小結果，再套用其他篩選：

# ✅ Efficient - date range first
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
  transactionType: ["GIFT_CARD_PURCHASE"]
  amountGte: 50.00
}

Rate Limits

Resource	Limit	Window
每位使用者的查詢數	100	1 minute
每個 IP 的查詢數	300	1 minute

Headers:

X-RateLimit-Limit - 允許的最大請求數
X-RateLimit-Remaining - 目前視窗內剩餘的請求數
X-RateLimit-Reset - 速率限制重置的時間（Unix 時間戳）

​Overview

​Declined Transaction

​Quick Start

​Variables

​Sample Request

​Sample Response

​Filter Options

​Pagination

​Best Practices

​1. 有效使用分頁

​2. 只請求所需欄位

​3. 針對歷史查詢使用日期篩選

​5. 有效率地組合篩選條件

​Rate Limits

Overview

Declined Transaction

Quick Start

Variables

Sample Request

Sample Response

Filter Options

Pagination

Best Practices

1. 有效使用分頁

2. 只請求所需欄位

3. 針對歷史查詢使用日期篩選

5. 有效率地組合篩選條件

Rate Limits