> ## 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.
# Obtener transacciones rechazadas
## Descripción general
La API de Transacciones Rechazadas te permite recuperar un historial completo de todas las transacciones financieras asociadas a tu cuenta que fueron rechazadas/fallidas. Esto incluye compras, depósitos, retiros, transferencias, pagos de facturas y todas las demás actividades financieras.
**Tipo de endpoint**: Consulta GraphQL\
**Autenticación**: Requerida (JWT Bearer Token)\
**Límite de tasa**: Se aplican los límites estándar de GraphQL
**Autorización requerida**
Esta mutación requiere los alcances `LIST_PAYMENT` y `LIST_PURCHASES`. Asegúrate de que tu token de acceso tenga concedido este alcance antes de intentar obtener una lista de transacciones rechazadas.
***
## Transacción rechazada
El objeto DeclineTransaction contiene información.
Aquí está la tabla:
| Nombre del campo | Tipo | Descripción |
| :-------------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transactionId` | `UUID!` | Identificador único de la transacción rechazada |
| `transactionType` | `String!` | Tipo de transacción que fue rechazada (p. ej., "Gift Card Purchase", "Virtual Card Purchase", "Add Money", "Withdrawal", "Transfer - Out", "Bill Payment Initiation", "Issue Virtual Card") |
| `amount` | `Float!` | Monto total de la transacción intentada, en la moneda de la transacción |
| `fluzAmount` | `Float!` | Porción financiada desde saldos internos de Fluz (efectivo/recompensas/reserva/prepago). Predetermina a 0 cuando no aplica |
| `externalFundingAmount` | `Float!` | Porción financiada desde una fuente externa (p. ej., banco/tarjeta vinculada). Predetermina a 0 cuando no aplica |
| `currency` | `String!` | Código de moneda ISO 4217. Predeterminado a "USD" cuando no se especifica |
| `sourceRecordType` | `String` | Tipo del registro de origen (p. ej., dominio/tipo de entidad de origen) |
| `sourceRecordId` | `String` | Identificador del registro de origen |
| `accountId` | `String!` | Identificador de la cuenta de Fluz que es dueña de la transacción |
| `userId` | `String` | Identificador del usuario que intentó la transacción. Puede estar ausente para transacciones a nivel de cuenta/sistema |
| `source` | `String` | Origen de los fondos / etiqueta de origen (p. ej., fuente de fondos o parte originadora) |
| `destination` | `String` | Etiqueta de destino (p. ej., comercio o destinatario). Normalmente el comercio para transacciones con comercios |
| `status` | `DeclinedTransactionStatus!` | Estado del resultado: `DECLINED` o `FAILED` |
| `merchantId` | `String` | Identificador del comercio asociado, cuando se conoce |
| `descriptorId` | `String` | Identificador del descriptor de comercio resuelto usado para enriquecer metadatos del comercio |
| `liabilityId` | `String` | Identificador del registro de obligación asociado, cuando aplica |
| `merchantName` | `String` | Nombre para mostrar del comercio. Se completa desde destination cuando se identifica un comercio |
| `merchantCountry` | `String` | País del comercio |
| `merchantCity` | `String` | Ciudad del comercio |
| `merchantState` | `String` | Estado/región del comercio |
| `logoUrl` | `String` | URL del logo a mostrar (normalmente el logo del comercio/marca) |
| `category` | `String` | Categoría/clasificación de la transacción o del comercio |
| `cardLastFour` | `String` | Últimos cuatro dígitos de la tarjeta utilizada |
| `cardDisplayName` | `String` | Nombre para mostrar, fácil de entender, de la tarjeta utilizada |
| `virtualCardId` | `String` | Identificador de la tarjeta virtual involucrada, cuando aplica |
| `channel` | `String` | Canal a través del cual se inició la transacción (p. ej., app, web, integración) |
| `externalFundingSourceType` | `String` | Tipo de fuente de fondos externa utilizada (p. ej., cuenta bancaria, tarjeta de débito) |
| `externalFundingSourceId` | `String` | Identificador de la fuente de fondos externa utilizada |
| `fundingSourceSubtype` | `String` | Subtipo de la fuente de fondos (p. ej., checking vs. savings, subtipo de red de tarjetas) |
| `isCashBalanceUsed` | `Boolean!` | Verdadero si se aplicó/intentó el saldo en efectivo del usuario |
| `isPrepaymentBalanceUsed` | `Boolean!` | Verdadero si se aplicó/intentó el saldo de prepago de tarjetas de regalo |
| `isRewardsBalanceUsed` | `Boolean!` | Verdadero si se aplicó/intentó el saldo de recompensas |
| `isReserveBalanceUsed` | `Boolean!` | Verdadero si se aplicó/intentó el saldo de reserva |
| `transactionDateTime` | `String!` | Marca de tiempo de la transacción como cadena ISO 8601 (derivada del momento de creación) |
| `spendAccountNickname` | `String` | Alias de la cuenta de gasto utilizada. Por defecto "Main account" cuando no está configurado |
| `declineTitle` | `String` | Título corto orientado al usuario que resume el rechazo |
| `declineReason` | `String` | Razón orientada al usuario que explica por qué se rechazó la transacción |
| `declineDescription` | `String` | Descripción más larga para el usuario con detalles adicionales del rechazo |
| `declineCtaText` | `String` | Texto de llamada a la acción que sugiere el siguiente paso para el usuario |
| `declineCategory` | `String` | Categorización del rechazo (utilizada para agrupar/dirigir la mensajería de rechazo) |
| `offerId` | `UUID` | Identificador de la oferta asociada, cuando aplica |
| `issuer` | `String` | Emisor de la tarjeta asociado con la tarjeta/transacción |
| `bin` | `String` | Bank Identification Number (primeros dígitos) de la tarjeta utilizada |
| `limitAmount` | `String` | Monto del límite de gasto relevante para el rechazo (p. ej., el límite excedido) |
| `limitDuration` | `String` | Duración/ventana a la que aplica el límite de gasto (p. ej., por transacción, diario, mensual) |
| `lockOnNextUse` | `String` | Indica si la tarjeta está configurada para bloquearse en el próximo uso |
| `lockDate` | `String` | Fecha asociada con un bloqueo de tarjeta, cuando aplica |
| `bankAccountNickname` | `String` | Alias de la cuenta bancaria asociada con la fuente de fondos |
| `bankAccountLastFour` | `String` | Últimos cuatro dígitos de la cuenta bancaria asociada con la fuente de fondos |
| `isPrivate` | `Boolean` | Indicador de privacidad que señala si la transacción debe tratarse como privada |
| `createdAt` | `DateTime!` | Marca de tiempo cuando se creó el registro de la transacción |
| `updatedAt` | `DateTime!` | Marca de tiempo cuando se actualizó por última vez el registro de la transacción |
## Inicio rápido
Para obtener una lista de transacciones rechazadas asociadas con tu cuenta, usa la consulta `getDeclinedTransactions`. Esta llamada devuelve una lista con detalles de transacciones rechazadas, incluyendo `transactionId`, `amount`, `status` y `destination`.
### Variables
| Campo | Tipo | Requerido | Descripción |
| ---------- | ---------------------------- | --------- | ------------------------------------------------------------- |
| `filter` | `UserCashBalanceFilterInput` | No | Criterios de filtrado para cuentas de gasto |
| `paginate` | `OffsetInput` | No | Parámetros de paginación (predeterminado: limit=20, offset=0) |
### Ejemplo de solicitud
```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
}
}
}
```
Ten en cuenta que, debido a la limitación de tasa, es posible que necesites paginar y llamar a la lista de transacciones rechazadas varias veces.
### Ejemplo de respuesta
La respuesta contendrá una lista de transacciones rechazadas
```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"
}
]
}
}
}
```
### Opciones de filtrado
| Campo | Tipo | Descripción |
| :------------------ | :---------------------------- | :------------------------------------------------------------------------------------------- |
| `transactionId` | `[UUID]` | Filtrar por IDs específicos de registros de transacciones |
| `status` | `[DeclinedTransactionStatus]` | Filtrar por estado (`DECLINED` o `FAILED`). Predeterminado a ambos cuando se omite |
| `amount` | `Float` | Filtrar por monto exacto |
| `amountGte` | `Float` | Filtrar por monto mínimo (mayor o igual) |
| `amountLte` | `Float` | Filtrar por monto máximo (menor o igual) |
| `fluzAmount` | `Float` | Filtrar por monto exacto de Fluz |
| `fluzAmountGte` | `Float` | Filtrar por monto mínimo de Fluz (mayor o igual) |
| `fluzAmountLte` | `Float` | Filtrar por monto máximo de Fluz (menor o igual) |
| `createdGte` | `DateTime` | Filtrar por fecha de creación (mayor o igual) |
| `createdLte` | `DateTime` | Filtrar por fecha de creación (menor o igual) |
| `updatedGte` | `DateTime` | Filtrar por fecha de última actualización (mayor o igual) |
| `updatedLte` | `DateTime` | Filtrar por fecha de última actualización (menor o igual) |
| `merchantId` | `[UUID]` | Filtrar por IDs de comercios |
| `merchant` | `[String]` | Filtrar por nombres de comercios (se compara con el campo `destination`) |
| `transactionType` | `[String]` | Filtrar por tipos de transacción (p. ej., `"Gift Card Purchase"`, `"Virtual Card Purchase"`) |
| `channel` | `[String!]` | Filtrar por canal (p. ej., `"UWP"`, `"app"`) |
| `category` | `[String]` | Filtrar por categoría de la transacción o del comercio |
| `virtualCardId` | `[UUID]` | Filtrar por IDs específicos de tarjetas virtuales |
| `fundingSource` | `[String]` | Filtrar por nombres de fuentes de fondos |
| `userCashBalanceId` | `[UUID]` | Filtrar por IDs de cuentas de gasto |
| `liabilityId` | `UUID` | Filtrar por ID de obligación (para transacciones de pago de facturas) |
**Ejemplo - Obtener solo** `DECLINED` **cuentas de gasto**
```json theme={null}
{
"filter": {
"status": [DECLINED]
}
}
```
### Paginación
| Campo | Tipo | Predeterminado | Máx | Descripción |
| -------- | ----- | -------------- | --- | --------------------------------------------- |
| `limit` | `Int` | 20 | 20 | Número de transacciones a devolver por página |
| `offset` | `Int` | 0 | - | Número de transacciones a omitir |
**Ejemplo - Página 1**:
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 0
}
}
```
**Ejemplo - Página 2**:
```json theme={null}
{
"paginate": {
"limit": 20,
"offset": 20,
}
}
```
***
## Mejores prácticas
### 1. Usa la paginación de forma efectiva
Siempre verifica `hasNextPage` para determinar si existen más resultados:
```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. Solicita solo los campos necesarios
Especifica únicamente los campos que necesitas para reducir el tamaño de la respuesta:
```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. Usa filtros de fecha para consultas históricas
Al consultar transacciones antiguas, utiliza siempre filtros de fecha:
```graphql theme={null}
# ✅ Good
filter: {
createdGte: "2024-01-01T00:00:00Z"
createdLte: "2024-12-31T23:59:59Z"
}
```
### 5. Combina filtros de forma eficiente
Usa filtros de rango para acotar resultados antes de aplicar otros filtros:
```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
}
```
***
## Límites de tasa
| Recurso | Límite | Ventana |
| --------------------- | ------ | -------- |
| Consultas por usuario | 100 | 1 minuto |
| Consultas por IP | 300 | 1 minuto |
**Encabezados**:
* `X-RateLimit-Limit` - Máximo de solicitudes permitidas
* `X-RateLimit-Remaining` - Solicitudes restantes en la ventana actual
* `X-RateLimit-Reset` - Momento en que se restablece el límite de tasa (timestamp Unix)