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

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

{
  "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

{
	"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:

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

Example - Page 2:

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

Best Practices

1. Use Pagination Effectively

Always check hasNextPage to determine if more results exist:

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:

# ✅ 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:

# ✅ 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:

# ✅ 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)