获取被拒绝的交易

Overview

已拒绝交易 API 允许您检索与您的账户相关的所有被拒绝/失败的金融交易的完整历史记录。这包括购买、存款、取款、转账、账单支付以及所有其他金融活动。 Endpoint Type: GraphQL Query
Authentication: Required (JWT Bearer Token)
Rate Limit: Standard GraphQL rate limits apply

需要授权此操作需要 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`	发起交易的渠道（例如应用、网页、集成）
`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!`	交易记录最后更新时的时间戳

快速入门

要获取与您的账户相关的被拒绝交易列表，请使用 getDeclinedTransactions 查询。此调用返回被拒绝交易的详细信息列表，包括 transactionId、amount、status 和 destination。

变量

Field	Type	Required	Description
`filter`	`UserCashBalanceFilterInput`	否	消费账户的筛选条件
`paginate`	`OffsetInput`	否	分页参数（默认：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]`	按特定交易记录 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]
  }
}

分页

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 共享相同的限制。有关具体数值以及被拒绝请求的样式，请参阅速率限制。

​Overview

​已拒绝交易

​快速入门

​变量

​请求示例

​响应示例

​筛选选项

​分页

​最佳实践

​1. 有效使用分页

​2. 仅请求所需字段

​3. 对历史查询使用日期筛选

​5. 高效组合筛选条件

​速率限制

Overview

已拒绝交易

快速入门

变量

请求示例

响应示例

筛选选项

分页

最佳实践

1. 有效使用分页

2. 仅请求所需字段

3. 对历史查询使用日期筛选

5. 高效组合筛选条件

速率限制