> ## 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.
# 获取已拒绝的交易
## 概览
已拒绝交易 API 允许你检索与你的账户相关、被拒绝/失败的所有金融交易的完整历史。这包括购买、充值、提现、转账、账单支付以及所有其他金融活动。
**端点类型**: GraphQL 查询\
**认证**: 必需（JWT Bearer Token）\
**速率限制**: 适用标准 GraphQL 速率限制
**需要授权**
此 mutation 需要 `LIST_PAYMENT` 和 `LIST_PURCHASES` 范围。请确保你的访问令牌已被授予该范围后再尝试获取已拒绝交易列表。
***
## 已拒绝交易
DeclineTransaction 对象包含信息。
下面是表格：
| 字段名 | 类型 | 描述 |
| :-------------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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、集成） |
| `externalFundingSourceType` | `String` | 使用的外部资金来源类型（例如银行账户、借记卡） |
| `externalFundingSourceId` | `String` | 使用的外部资金来源标识符 |
| `fundingSourceSubtype` | `String` | 资金来源的子类型（例如支票账户 vs. 储蓄账户、卡网络子类型） |
| `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`。
### 变量
| 字段 | 类型 | 必填 | 描述 |
| ---------- | ---------------------------- | -- | --------------------------- |
| `filter` | `UserCashBalanceFilterInput` | 否 | 消费账户的筛选条件 |
| `paginate` | `OffsetInput` | 否 | 分页参数（默认：limit=20, offset=0） |
### 示例请求
```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
}
}
}
```
请注意，由于速率限制，你可能需要进行分页并多次调用已拒绝交易列表。
### 示例响应
响应将包含已拒绝交易的列表
```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"
}
]
}
}
}
```
### 筛选选项
| 字段 | 类型 | 描述 |
| :------------------ | :---------------------------- | :----------------------------------------------------------- |
| `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]
}
}
```
### 分页
| 字段 | 类型 | 默认 | 最大 | 描述 |
| -------- | ----- | -- | -- | --------- |
| `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,
}
}
```
***
## 最佳实践
### 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
}
```
***
## 速率限制
| 资源 | 限额 | 窗口 |
| -------- | --- | ---- |
| 每用户查询数 | 100 | 1 分钟 |
| 每 IP 查询数 | 300 | 1 分钟 |
**响应头**:
* `X-RateLimit-Limit` - 允许的最大请求数
* `X-RateLimit-Remaining` - 当前窗口剩余请求数
* `X-RateLimit-Reset` - 速率限制重置时间（Unix 时间戳）