> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 取得被拒絕的交易
## 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
```graphql theme={null}
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
回應將包含被拒絕交易的清單
```json theme={null}
{
"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"
}
]
}
}
}
```
### Filter Options
| 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` **的消費帳戶**
```json theme={null}
{
"filter": {
"status": [DECLINED]
}
}
```
### Pagination
| Field | Type | Default | Max | Description |
| -------- | ----- | ------- | --- | ----------- |
| `limit` | `Int` | 20 | 20 | 每頁要回傳的交易數量 |
| `offset` | `Int` | 0 | - | 要略過的交易數量 |
**範例 - 第 1 頁**：
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 0
}
}
```
**範例 - 第 2 頁**：
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 20,
}
}
```
***
## Best Practices
### 1. 有效使用分頁
總是檢查 `hasNextPage` 以判斷是否仍有更多結果：
```javascript theme={null}
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. 只請求所需欄位
僅指定你需要的欄位以減少回應大小：
```graphql theme={null}
# ✅ 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. 針對歷史查詢使用日期篩選
查詢較早期的交易時，務必使用日期篩選：
```graphql theme={null}
# ✅ Good
filter: {
createdGte: "2024-01-01T00:00:00Z"
createdLte: "2024-12-31T23:59:59Z"
}
```
### 5. 有效率地組合篩選條件
先使用範圍篩選縮小結果，再套用其他篩選：
```graphql theme={null}
# ✅ 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 時間戳）