取得已拒絕交易

概觀

已拒絕交易 API 可讓你取得帳戶所有遭拒絕或失敗的財務交易完整歷史記錄。這包括購買、存款、提款、轉帳、帳單繳費，以及所有其他財務活動。 端點類型: GraphQL Query
驗證: 必需（JWT Bearer Token）
速率限制: 套用標準 GraphQL 速率限制

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

已拒絕交易

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`	使用卡片的銀行識別碼（BIN，卡號開頭數字）
`limitAmount`	`String`	與此次拒絕相關的消費限額金額（例如超出的限額）
`limitDuration`	`String`	消費限額適用的期間/區間（例如單筆交易、每日、每月）
`lockOnNextUse`	`String`	指出卡片是否設定為下次使用時鎖定
`lockDate`	`String`	適用時，與卡片鎖定相關的日期
`bankAccountNickname`	`String`	與資金來源關聯的銀行帳戶暱稱
`bankAccountLastFour`	`String`	與資金來源關聯的銀行帳戶末四碼
`isPrivate`	`Boolean`	指出此交易是否應視為私密的隱私旗標
`createdAt`	`DateTime!`	交易記錄的建立時間戳記
`updatedAt`	`DateTime!`	交易記錄的最後更新時間戳記

快速開始

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

變數

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

範例請求

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

每頁最多回傳 20 筆已拒絕交易，因此請使用分頁以取得完整清單。

範例回應

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

{
  "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]`	依特定交易記錄識別碼篩選
`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]`	依商家識別碼篩選
`merchant`	`[String]`	依商家名稱篩選（與 `destination` 欄位比對）
`transactionType`	`[String]`	依交易類型篩選（例如 `"Gift Card Purchase"`、`"Virtual Card Purchase"`）
`channel`	`[String!]`	依管道篩選（例如 `"UWP"`、`"app"`）
`category`	`[String]`	依交易或商家類別篩選
`virtualCardId`	`[UUID]`	依特定虛擬卡識別碼篩選
`fundingSource`	`[String]`	依資金來源名稱篩選
`userCashBalanceId`	`[UUID]`	依消費帳戶識別碼篩選
`liabilityId`	`UUID`	依負債識別碼篩選（適用於帳單繳費交易）

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

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

分頁

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

範例 - 第 1 頁:

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

範例 - 第 2 頁:

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

最佳實務

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
}

速率限制

此查詢與 GraphQL API 共用相同的限制。詳細數字與遭拒絕請求的樣貌請參閱速率限制。

​概觀

​已拒絕交易

​快速開始

​變數

​範例請求

​範例回應

​篩選選項

​分頁

​最佳實務

​1. 有效使用分頁

​2. 僅請求所需欄位

​3. 查詢歷史資料時使用日期篩選

​5. 高效組合篩選條件

​速率限制

概觀

已拒絕交易

快速開始

變數

範例請求

範例回應

篩選選項

分頁

最佳實務

1. 有效使用分頁

2. 僅請求所需欄位

3. 查詢歷史資料時使用日期篩選

5. 高效組合篩選條件

速率限制