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, pueden reintentarse, pero con límites: Visa limita los reintentos con la misma tarjeta dentro de 30 días y cobra cargos por encima de ese límite.
• Rechazos duros (hard decline), como tarjeta robada o cuenta inválida, no deben reintentarse de forma automática. Visa cobra un cargo por cualquier reintento tras un rechazo de Categoría 1 ("el emisor nunca aprobará"), y Mastercard cobra por los reintentos tras los Merchant Advice Codes 03 y 21.
• Los fallos de autenticación deberían volver al flujo de 3D Secure.
• Los errores de procesamiento deberían reintentarse con espera progresiva (backoff), usando la misma clave de idempotencia para que un reintento nunca genere un segundo cobro.

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, así que en producción hay que contar con eventos duplicados.
• Prueba eventos fuera de orden (por ejemplo, charge.refunded que llega antes de payment_intent.succeeded, o invoice.paid antes de invoice.created); las pasarelas no garantizan el orden de entrega.
• 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 (JPY), monedas con tres decimales (BHD, KWD), el redondeo ni las unidades de amount en la unidad mínima de la moneda.
• Asumir que una autorización exitosa significa que el dinero se liquidó: la captura todavía puede fallar después, y las autorizaciones vencen (en Stripe, a los 7 días para la mayoría de los pagos con tarjeta en línea).

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.