> ## 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.
# Get Declined Transactions
## Overview
The Declined Transactions API allows you to retrieve a comprehensive history of all financial transactions associated with your account that were declined/failed. This includes purchases, deposits, withdrawals, transfers, bill payments, and all other financial activities.
**Endpoint Type**: GraphQL Query\
**Authentication**: Required (JWT Bearer Token)\
**Rate Limit**: Standard GraphQL rate limits apply
**Authorization required**
This mutation requires `LIST_PAYMENT` & `LIST_PURCHASES` scopes. Ensure your access token has been granted this scope before attempting to get a list of declined transactions.
***
## Declined Transaction
The DeclineTransaction object contains information.
Here's the table:
| Field name | Type | Description |
| :-------------------------- | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId` | `UUID!` | Unique identifier of the declined transaction |
| `transactionType` | `String!` | Type of transaction that was declined (e.g. "Gift Card Purchase", "Virtual Card Purchase", "Add Money", "Withdrawal", "Transfer - Out", "Bill Payment Initiation", "Issue Virtual Card") |
| `amount` | `Float!` | Total transaction amount attempted, in the transaction's currency |
| `fluzAmount` | `Float!` | Portion funded from Fluz internal balances (cash/rewards/reserve/prepayment). Defaults to 0 when not applicable |
| `externalFundingAmount` | `Float!` | Portion funded from an external source (e.g. linked bank/card). Defaults to 0 when not applicable |
| `currency` | `String!` | ISO 4217 currency code. Defaults to "USD" when not specified |
| `sourceRecordType` | `String` | Type of the originating source record (e.g. originating domain/entity type) |
| `sourceRecordId` | `String` | Identifier of the originating source record |
| `accountId` | `String!` | Identifier of the Fluz account that owns the transaction |
| `userId` | `String` | Identifier of the user who attempted the transaction. May be absent for account-level/system transactions |
| `source` | `String` | Source of funds / origin label (e.g. funding source or originating party) |
| `destination` | `String` | Destination label (e.g. merchant or recipient). Typically the merchant for merchant transactions |
| `status` | `DeclinedTransactionStatus!` | Outcome status: `DECLINED` or `FAILED` |
| `merchantId` | `String` | Identifier of the associated merchant, when known |
| `descriptorId` | `String` | Identifier of the resolved merchant descriptor used to enrich merchant metadata |
| `liabilityId` | `String` | Identifier of the associated liability record, when applicable |
| `merchantName` | `String` | Display name of the merchant. Populated from destination when a merchant is identified |
| `merchantCountry` | `String` | Country of the merchant |
| `merchantCity` | `String` | City of the merchant |
| `merchantState` | `String` | State/region of the merchant |
| `logoUrl` | `String` | URL of the logo to display (typically the merchant/brand logo) |
| `category` | `String` | Category/classification of the transaction or merchant |
| `cardLastFour` | `String` | Last four digits of the card used |
| `cardDisplayName` | `String` | Human-friendly display name of the card used |
| `virtualCardId` | `String` | Identifier of the virtual card involved, when applicable |
| `channel` | `String` | Channel through which the transaction was initiated (e.g. app, web, integration) |
| `externalFundingSourceType` | `String` | Type of external funding source used (e.g. bank account, debit card) |
| `externalFundingSourceId` | `String` | Identifier of the external funding source used |
| `fundingSourceSubtype` | `String` | Subtype of the funding source (e.g. checking vs. savings, card network subtype) |
| `isCashBalanceUsed` | `Boolean!` | True if the user's cash balance was applied/attempted |
| `isPrepaymentBalanceUsed` | `Boolean!` | True if the gift-card prepayment balance was applied/attempted |
| `isRewardsBalanceUsed` | `Boolean!` | True if the rewards balance was applied/attempted |
| `isReserveBalanceUsed` | `Boolean!` | True if the reserve balance was applied/attempted |
| `transactionDateTime` | `String!` | Timestamp of the transaction as an ISO 8601 string (derived from creation time) |
| `spendAccountNickname` | `String` | Nickname of the spend account used. Falls back to "Main account" when not set |
| `declineTitle` | `String` | Short user-facing title summarizing the decline |
| `declineReason` | `String` | User-facing reason explaining why the transaction was declined |
| `declineDescription` | `String` | Longer user-facing description with additional decline detail |
| `declineCtaText` | `String` | Call-to-action text suggesting the next step for the user |
| `declineCategory` | `String` | Categorization of the decline (used to group/route decline messaging) |
| `offerId` | `UUID` | Identifier of the associated offer, when applicable |
| `issuer` | `String` | Card issuer associated with the card/transaction |
| `bin` | `String` | Bank Identification Number (first digits) of the card used |
| `limitAmount` | `String` | Spend-limit amount relevant to the decline (e.g. the limit exceeded) |
| `limitDuration` | `String` | Duration/window the spend limit applies to (e.g. per-transaction, daily, monthly) |
| `lockOnNextUse` | `String` | Indicates whether the card is set to lock on next use |
| `lockDate` | `String` | Date associated with a card lock, when applicable |
| `bankAccountNickname` | `String` | Nickname of the bank account associated with the funding source |
| `bankAccountLastFour` | `String` | Last four digits of the bank account associated with the funding source |
| `isPrivate` | `Boolean` | Privacy flag indicating whether the transaction should be treated as private |
| `createdAt` | `DateTime!` | Timestamp when the transaction record was created |
| `updatedAt` | `DateTime!` | Timestamp when the transaction record was last updated |
## Quick Start
To obtain a list of declined transactions associated with your account, use the `getDeclinedTransactions` query. This call returns a list of declined transactions details, including the `transactionId`, `amount` , `status` & `destination`.
### Variables
| Field | Type | Required | Description |
| ---------- | ---------------------------- | -------- | --------------------------------------------------- |
| `filter` | `UserCashBalanceFilterInput` | No | Filtering criteria for spend accounts |
| `paginate` | `OffsetInput` | No | Pagination parameters (default: 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
}
}
}
```
Please note that due to rate-limiting, you might need to paginate and call the declined transactions list a few times.
### Sample Response
The response will contain a list of declined transactions
```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]` | Filter by specific transaction record IDs |
| `status` | `[DeclinedTransactionStatus]` | Filter by status (`DECLINED` or `FAILED`). Defaults to both when omitted |
| `amount` | `Float` | Filter by exact amount |
| `amountGte` | `Float` | Filter by minimum amount (greater than or equal) |
| `amountLte` | `Float` | Filter by maximum amount (less than or equal) |
| `fluzAmount` | `Float` | Filter by exact Fluz amount |
| `fluzAmountGte` | `Float` | Filter by minimum Fluz amount (greater than or equal) |
| `fluzAmountLte` | `Float` | Filter by maximum Fluz amount (less than or equal) |
| `createdGte` | `DateTime` | Filter by creation date (greater than or equal) |
| `createdLte` | `DateTime` | Filter by creation date (less than or equal) |
| `updatedGte` | `DateTime` | Filter by last updated date (greater than or equal) |
| `updatedLte` | `DateTime` | Filter by last updated date (less than or equal) |
| `merchantId` | `[UUID]` | Filter by merchant IDs |
| `merchant` | `[String]` | Filter by merchant names (matched against `destination` field) |
| `transactionType` | `[String]` | Filter by transaction types (e.g. `"Gift Card Purchase"`, `"Virtual Card Purchase"`) |
| `channel` | `[String!]` | Filter by channel (e.g. `"UWP"`, `"app"`) |
| `category` | `[String]` | Filter by transaction or merchant category |
| `virtualCardId` | `[UUID]` | Filter by specific virtual card IDs |
| `fundingSource` | `[String]` | Filter by funding source names |
| `userCashBalanceId` | `[UUID]` | Filter by spend account IDs |
| `liabilityId` | `UUID` | Filter by liability ID (for bill payment transactions) |
**Example - Get only** `DECLINED `**spend accounts**
```json theme={null}
{
"filter": {
"status": [DECLINED]
}
}
```
### Pagination
| Field | Type | Default | Max | Description |
| -------- | ----- | ------- | --- | ----------------------------------------- |
| `limit` | `Int` | 20 | 20 | Number of transactions to return per page |
| `offset` | `Int` | 0 | - | Number of transactions to skip |
**Example - Page 1**:
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 0
}
}
```
**Example - Page 2**:
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 20,
}
}
```
***
## Best Practices
### 1. Use Pagination Effectively
Always check `hasNextPage` to determine if more results exist:
```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. Request Only Needed Fields
Specify only the fields you need to reduce response size:
```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. Use Date Filters for Historical Queries
When querying older transactions, always use date filters:
```graphql theme={null}
# ✅ Good
filter: {
createdGte: "2024-01-01T00:00:00Z"
createdLte: "2024-12-31T23:59:59Z"
}
```
### 5. Combine Filters Efficiently
Use range filters to narrow results before applying other filters:
```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 |
| ---------------- | ----- | -------- |
| Queries per user | 100 | 1 minute |
| Queries per IP | 300 | 1 minute |
**Headers**:
* `X-RateLimit-Limit` - Maximum requests allowed
* `X-RateLimit-Remaining` - Requests remaining in current window
* `X-RateLimit-Reset` - Time when the rate limit resets (Unix timestamp)