> ## 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.
# Simular transacciones con tarjeta
> Pon un gasto de prueba en una tarjeta virtual de staging: cómo solicitar una autorización, clearing, rechazo o reembolso, y cómo verificar el resultado por la API.
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 staging**
Las 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 Fluz**
No 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](mailto: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.
Las tarjetas solo pueden emitirse — y solo autorizan — en una cuenta verificada. Consulta [Probar flujos de KYC](/test-kyc-flows) para identidades que devuelven un pase.
Emite una con `createVirtualCard` usando una oferta de [Ofertas de tarjetas virtuales de prueba](/test-virtual-card-offers). Conserva el `virtual_card_id`: así localizamos la tarjeta.
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.
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.
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.
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](/features/decline-codes) para el conjunto completo.
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.
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.
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.
```graphql Transactions on the card theme={null}
query {
getVirtualCardTransactions(input: {
virtualCardIds: [""]
filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
}) {
virtualCardId
transactions {
transactionId
transactionDate
transactionType
transactionStatus
transactionAmount
transactionApproval
transactionResponseCode
merchantName
merchantDescriptor
mcc
}
}
}
```
```graphql Balance after the spend theme={null}
query {
getVirtualCardBalance(input: {
virtualCardIds: [""]
}) {
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](/features/get-decline-transactions).
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](/features/transactions-details-overview).
### 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](/fluz-dashboard/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
El camino feliz completo: elige un programa, emite una tarjeta, revélala y haz seguimiento de su gasto.
Filtra la actividad de la tarjeta por tipo y rango de fechas, y lee cada campo de una transacción.
Cada motivo y categoría de rechazo, y qué debería hacer tu app con cada uno.
Suscríbete a eventos de transacción, verifica firmas y maneja reintentos.
**¿Quieres saber más?** Contáctanos en [partnerships@fluz.app](mailto:partnerships@fluz.app). Habla con nuestros expertos para más información o para solicitar una demostración.