Pruebas de pasarelas de pago: guía práctica para desarrolladores

Los pagos con tarjeta son la única parte de tu aplicación donde un bug cuesta dinero real. Probar contra el sandbox de una pasarela de pago es la única forma segura de ejercitar rechazos, 3D Secure, reembolsos y webhooks, y hacerlo bien depende más de la disciplina que de las herramientas.

Esta guía cubre el flujo de trabajo que funciona con Stripe, Adyen, Braintree y la mayoría de las demás pasarelas, además de los modos de fallo que toman por sorpresa a los equipos.

1. Separa las credenciales de prueba y de producción

Cada pasarela de pago te da un universo paralelo: claves de API de prueba, endpoints de prueba y números de tarjeta de prueba. Mantenlos separados en todas las capas:

• Archivos .env y gestores de secretos distintos, nunca una sola variable STRIPE_KEY.
• Un fallo inmediato al arrancar si una clave de prueba llega a producción o si se usa una clave de producción en CI.
• Un aviso visible en staging para que nadie dude del entorno que está viendo.

La causa más común de "le cobramos a un cliente real en pruebas" es una combinación de configuración que promovió una clave de producción sin que nadie lo notara.

2. Usa primero las tarjetas de prueba de la propia pasarela

Los números de prueba del proveedor están conectados a comportamientos específicos que ningún número generado puede reproducir. Stripe, por ejemplo, asocia cada número con un código de rechazo:

Nuestra referencia de números de tarjetas de prueba reúne los números oficiales de Stripe, Adyen y Braintree en una sola tabla. Úsalos para probar el comportamiento de la pasarela y usa el generador de tarjetas cuando necesites números para un BIN, una marca de tarjeta o un volumen específicos.

3. Prueba los rechazos como estados de primera clase

Un pago rechazado es un resultado normal, no un error. Tu código debería ramificarse según el motivo del rechazo, no solo ante un "falló":

• Rechazos suaves (soft decline), como fondos insuficientes, deberían ofrecer un reintento.
• Rechazos duros (hard decline), como tarjeta robada o cuenta inválida, no deben reintentarse de forma automática.
• Los fallos de autenticación deberían volver al flujo de 3D Secure.
• Los errores de procesamiento deberían reintentarse con espera progresiva (backoff).

Registra el código de error de la pasarela, no solo el mensaje, y guarda la respuesta sin procesar para los tickets de soporte.

4. Simula 3D Secure

Las redirecciones, los iframes y los flujos de desafío de 3DS son donde viven la mayoría de los bugs de checkout. Prueba al menos:

• Autenticación sin fricción (sin interacción del usuario).
• El flujo de desafío, incluido un desafío fallido y uno cancelado.
• El botón de atrás del navegador después de la redirección.
• Los navegadores integrados en apps móviles.

Stripe publica tarjetas de prueba específicas para cada flujo; consulta la guía de pruebas de 3D Secure para ver la lista y qué activa cada tarjeta.

5. Verifica los webhooks, la idempotencia y el orden

La respuesta síncrona de la API es solo la mitad de la historia. El estado del dinero normalmente se define con webhooks, así que prueba ese camino con el mismo cuidado que el checkout:

• Reenvía el mismo evento de webhook dos veces y verifica la idempotencia. La mayoría de las pasarelas reintenta ante respuestas que no son 2xx, y los eventos duplicados están garantizados en producción.
• Prueba eventos fuera de orden (por ejemplo, un reembolso que llega antes de la captura).
• Valida las firmas de los webhooks y rechaza las solicitudes sin firma.
• Haz que los handlers sean rápidos: confirma la recepción en pocos segundos y procesa de forma asíncrona.
• Las herramientas de CLI stripe listen --forward-to y stripe trigger de Stripe facilitan el reenvío local; Adyen y Braintree ofrecen simuladores de notificaciones equivalentes.

6. Lleva el sandbox a CI

Haz una prueba de humo del flujo de pago en cada despliegue, no solo de forma manual:

1. Crea un pago de prueba con una tarjeta de éxito.
2. Verifica el estado en la base de datos, el asiento contable y la notificación por correo.
3. Crea un pago rechazado y verifica el error que ve el usuario.
4. Dispara el webhook de la pasarela y verifica la transición de estado.
5. Emite un reembolso y verifica la reversión.

Mantén estas pruebas solo en el sandbox y etiquétalas para que puedan ejecutarse aparte de las pruebas unitarias rápidas.

7. Lista de errores comunes

• Mezclar claves de prueba y de producción entre servicios (un clásico en arquitecturas de microservicios).
• Fijar fechas de vencimiento en el pasado: usa una fecha muy lejana para que las pruebas de "tarjeta vencida" sean intencionales.
• Probar solo el camino feliz y olvidar la cancelación de 3DS.
• Ignorar la verificación de la firma de los webhooks porque "funciona en local".
• Construir lógica de reintento que reintenta rechazos duros.
• No probar monedas sin decimales, el redondeo ni las unidades de amount.
• Asumir que una autorización exitosa significa que el dinero se liquidó: la captura todavía puede fallar después.

Próximos pasos

• Toma los números oficiales de la lista de números de tarjetas de prueba.
• Genera datos de prueba para cualquier BIN con el generador de tarjetas o enumera patrones con el generador avanzado.
• Valida números en tu suite de pruebas con la guía del validador de Luhn.

Probar pagos no es glamoroso, pero es uno de los hábitos con mayor retorno para un equipo: un par de horas en el sandbox evitan con frecuencia incidentes que cuestan mucho más que el tiempo de ingeniería.