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 requeridaEsta 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

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

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

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

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

Ejemplo - Página 2:

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

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:

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

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

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

​Descripción general

​Transacción rechazada

​Inicio rápido

​Variables

​Ejemplo de solicitud

​Ejemplo de respuesta

​Opciones de filtrado

​Paginación

​Mejores prácticas

​1. Usa la paginación de forma efectiva

​2. Solicita solo los campos necesarios

​3. Usa filtros de fecha para consultas históricas

​5. Combina filtros de forma eficiente

​Límites de tasa

Descripción general

Transacción rechazada

Inicio rápido

Variables

Ejemplo de solicitud

Ejemplo de respuesta

Opciones de filtrado

Paginación

Mejores prácticas

1. Usa la paginación de forma efectiva

2. Solicita solo los campos necesarios

3. Usa filtros de fecha para consultas históricas

5. Combina filtros de forma eficiente

Límites de tasa