Simular transacciones con tarjeta

Las tarjetas virtuales de staging son registros de tarjetas reales con BINs reales, pero no están en una red de pago activa: ningún comercio puede pasarlas. Para ejercitar tu lógica de gasto, balance y conciliación, Fluz inyecta una autorización contra tu tarjeta a través del entorno de prueba del procesador emisor. Todo lo que sigue a partir de ese punto es el camino de código de producción: el mismo servicio de autorizaciones, los mismos controles de gasto, las mismas entradas en el libro mayor, los mismos webhooks.

Solo en stagingLas transacciones simuladas existen únicamente en el entorno de staging (https://transactional-graph.staging.fluzapp.com/api/v1/graphql). No se mueven fondos, no se genera interchange y no se envía nada a Mastercard. En producción, las transacciones llegan solo de actividad real de comercios.

Las simulaciones las dispara FluzNo hay una mutación pública que inyecte una transacción en una tarjeta. La simulación de autorización ocurre en el dashboard del procesador emisor, que está dentro del entorno PCI de Fluz y no está expuesto a partners. Solicita las transacciones que necesites por tu canal de integración (canal compartido de Slack o partnerships@fluz.app) y las ejecutaremos contra tu tarjeta, usualmente el mismo día hábil. Todo lo demás en esta página — emitir la tarjeta, leer el resultado — es totalmente self-serve.

Antes de solicitar una simulación

Una autorización pasa por toda la pila de controles, así que una tarjeta que no esté configurada correctamente rechazará por razones que no tienen nada que ver con tu prueba.

La cuenta pasó KYC

Las tarjetas solo pueden emitirse — y solo autorizan — en una cuenta verificada. Consulta Probar flujos de KYC para identidades que devuelven un pase.

Tienes una tarjeta ACTIVA

Emite una con createVirtualCard usando una oferta de Ofertas de tarjetas virtuales de prueba. Conserva el virtual_card_id: así localizamos la tarjeta.

La tarjeta está fondeada y desbloqueada

La tarjeta se alimenta de tu balance de Fluz. Confirma que el límite de gasto cubre tu monto de prueba y que la tarjeta no esté bloqueada, vencida o agotada. getVirtualCardBalance te muestra remainingBalance de un vistazo.

Qué puedes simular

Pide la etapa del ciclo de vida que necesites. Cada una se mapea a un conjunto distinto de registros y webhooks de tu lado.

Autorización (aprobación)

El caso base: una compra en un comercio que indiques, por un monto que indiques. El balance disponible de la tarjeta se reduce inmediatamente y la transacción queda en estado pendiente. Úsalo para verificar que los controles de gasto, la disminución del balance y tu manejador de TRANSACTION_CREATE se comporten correctamente.

Clearing (captura)

La etapa de liquidación que sigue a una autorización, a veces días después en el mundo real. Podemos capturar en un solo paso junto con la autorización, o dejar la autorización abierta para que observes el estado pendiente y luego solicites la captura por separado. La segunda opción es la más fiel a producción.

Rechazo

Una transacción que el servicio de autorizaciones rechaza. Indícanos qué rechazo quieres ver: un rechazo por controles (por encima del límite de gasto, comercio equivocado en una tarjeta bloqueada por marca, tarjeta bloqueada) o un rechazo por autenticación (CVV incorrecto). Los rechazos exponen un declineReason y declineCategory; consulta Códigos de rechazo para el conjunto completo.

Reversa

Una autorización liberada antes de que liquide — el comercio abandonó la venta o el terminal se agotó por timeout. El monto retenido regresa a la tarjeta. Vale la pena probarlo si concilias sobre autorizaciones en lugar de liquidaciones.

Reembolso

Valor devuelto a la tarjeta después de que una compra ha liquidado, total o parcialmente. Aparece como un tipo de transacción REFUND en lugar de una reducción de la compra original, por lo que tu libro mayor debe manejarlo como un registro separado.

Verificaciones de cero dólares y AVS

Algunos comercios prueban una tarjeta con una autorización de

0.00 o

0.01 antes de cobrarla. Estas aparecen como sus propios registros y se revierten poco después. Si tu conciliación suma autorizaciones, prueba este caso: es una fuente común de doble conteo.

Qué debes enviarnos

Cuanto más de esto proporciones, menos idas y vueltas.

Campo	Requerido	Notas
`virtual_card_id`	Sí	Devuelto por `createVirtualCard`. También funcionan los últimos cuatro de la tarjeta.
Monto	Sí	En USD.
Resultado	Sí	Aprobar o rechazar — y si es rechazo, qué motivo quieres ejercitar.
Nombre del comercio	No	Predetermina a un comercio de prueba genérico. Establécelo si haces matching por descriptores.
MCC	No	Establécelo si pruebas lógica basada en categoría.
Clearing en un solo paso	No	Activado para capturar inmediatamente; desactivado para dejar la autorización pendiente.

Verificar el resultado

Una vez que confirmemos que la simulación se ejecutó, todo es legible por la API. Nada sobre leer una transacción simulada difiere de leer una real.

query {
  getVirtualCardTransactions(input: {
    virtualCardIds: ["<virtual_card_id>"]
    filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
  }) {
    virtualCardId
    transactions {
      transactionId
      transactionDate
      transactionType
      transactionStatus
      transactionAmount
      transactionApproval
      transactionResponseCode
      merchantName
      merchantDescriptor
      mcc
    }
  }
}

query {
  getVirtualCardBalance(input: {
    virtualCardIds: ["<virtual_card_id>"]
  }) {
    virtualCardId
    spentAmount
    remainingBalance
    spendLimit
    spendLimitDuration
  }
}

Una compra simulada debería aparecer como una fila PURCHASE con una caída correspondiente en remainingBalance. Un rechazo aparece bajo el tipo DECLINE y deja el balance intacto — los rechazos también se pueden consultar de forma aislada mediante Obtener transacciones rechazadas.

Las consultas a nivel de tarjeta solo cubren la actividad de la tarjeta. Para ver el mismo evento en el libro mayor unificado de la cuenta junto con depósitos y transferencias, usa getTransactions — consulta Descripción general de transacciones.

Webhooks

Las transacciones simuladas disparan los mismos eventos que las reales, lo que hace que esta sea la forma más limpia de probar tu endpoint de extremo a extremo:

Evento	Dispara cuando
`TRANSACTION_CREATE`	Se aprueba la autorización. `status` es `PENDING`.
`TRANSACTION_UPDATE`	La transacción liquida. `status` pasa a `SETTLED`.
`TRANSACTION_DECLINE`	Se rechaza la autorización, con `declineReason` y `declineCategory`.

Si solicitaste una autorización sin clearing en un solo paso, deberías ver TRANSACTION_CREATE por sí solo y TRANSACTION_UPDATE solo después de que se ejecute la captura. Consulta Webhooks para cargas útiles y verificación de firmas.

Solución de problemas

Lo que ves	Causa probable
Rechazada cuando esperabas una aprobación	Límite de gasto por debajo del monto, tarjeta bloqueada, balance de Fluz insuficiente o una tarjeta bloqueada por marca en el comercio equivocado.
No aparece nada en la tarjeta	La simulación se ejecutó contra otra tarjeta. Confirma el `virtual_card_id` que enviaste.
La transacción permanece pendiente	Esperado — la autorización no ha sido capturada. Solicita la etapa de clearing.
No se recibió webhook	Revisa la suscripción y los alcances requeridos; la transacción en sí sigue siendo visible por la API.
El balance no se mueve en un cargo de $0.01	Esperado para una prueba AVS. Se revierte por sí sola.

Próximos pasos

Tu primera compra con tarjeta virtual

El camino feliz completo: elige un programa, emite una tarjeta, revélala y haz seguimiento de su gasto.

Obtener transacciones de tarjetas virtuales

Filtra la actividad de la tarjeta por tipo y rango de fechas, y lee cada campo de una transacción.

Códigos de rechazo

Cada motivo y categoría de rechazo, y qué debería hacer tu app con cada uno.

Webhooks

Suscríbete a eventos de transacción, verifica firmas y maneja reintentos.

¿Quieres saber más? Contáctanos en partnerships@fluz.app. Habla con nuestros expertos para más información o para solicitar una demostración.

Comienza

Panel de Fluz

Guías rápidas

Simular transacciones con tarjeta

Antes de solicitar una simulación

Qué puedes simular

Qué debes enviarnos

Verificar el resultado

Webhooks

Solución de problemas

Próximos pasos

Tu primera compra con tarjeta virtual

Obtener transacciones de tarjetas virtuales

Códigos de rechazo

Webhooks

​Antes de solicitar una simulación

​Qué puedes simular

​Qué debes enviarnos

​Verificar el resultado

​Webhooks

​Solución de problemas

​Próximos pasos

Tu primera compra con tarjeta virtual

Obtener transacciones de tarjetas virtuales

Códigos de rechazo

Webhooks

Antes de solicitar una simulación

Qué puedes simular

Qué debes enviarnos

Verificar el resultado

Webhooks

Solución de problemas

Próximos pasos