Pruebas de pagos con tarjeta

Al integrar flujos de pago en el entorno Sandbox de TropiPay (https://sandbox.tropipay.me), debes usar tarjetas de pago de prueba dedicadas para simular ciclos de vida de transacciones, autenticaciones y escenarios de error.

Restricciones del entorno

• Las tarjetas reales NO funcionarán en el entorno Sandbox.
• Las tarjetas de prueba de Sandbox NO funcionarán en Producción.
• Nunca intentes procesar datos reales de tarjetahabientes ni tarjetas de crédito/débito en vivo en Sandbox.

---

Enrutamiento de moneda y pasarela (TPV)

TropiPay enruta las transacciones dinámicamente a través de múltiples pasarelas de pago (TPVs) basándose en varios factores, incluyendo:

• Moneda de la cuenta: cuentas en EUR, cuentas en USD, o cuentas denominadas en cripto/monedas estables (USDT / USDC).
• Asignación de pasarela del comercio (TPV): Determinada por la paymentEntity asignada a tu cuenta de procesamiento.

Mapeo de entidad de pago y conjunto de tarjetas

Conjunto de tarjetas	Monedas principales de la cuenta	paymentEntity	Notas
Conjunto #1	Cuentas en EUR	1	Pasarela de autenticación 3DS multimarca
Conjunto #2	Cuentas multidivisa	2, 4	Procesamiento Visa/Mastercard de doble escenario
Conjunto #3	Cuentas multidivisa	1, 3	Simulador estándar y escenarios de error

Debido a que las reglas de procesamiento de pagos y las configuraciones de pasarelas pueden variar o cambiar dinámicamente, si una tarjeta de un conjunto no procesa como se espera en tu configuración de sandbox, prueba con una tarjeta de otro conjunto.

Directrices generales para tarjetas de prueba de Sandbox

A menos que se especifique lo contrario en un escenario de prueba:

• Nombre del tarjetahabiente: Cualquier nombre (por ejemplo, John Doe).
• Fecha de expiración: Cualquier fecha futura válida (por ejemplo, 12/30).
• Código de seguridad (CVV / CVC): Cualquier número de 3 dígitos (por ejemplo, 123), o 4 dígitos para American Express (por ejemplo, 1234).
• OTP 3D Secure (3DS): Cuando se solicite verificación SMS/OTP en Sandbox, usa 123456.

---

Conjuntos de tarjetas de prueba

Conjunto #1: Pruebas de pasarela multimarca (paymentEntity: 1, cuentas en EUR)

Este conjunto se usa principalmente en cuentas en EUR con paymentEntity: 1 y permite probar ciclos de vida de autenticación 3D Secure estándar en las principales redes de tarjetas.

Autenticación exitosa

Marca	Número de tarjeta	Estado esperado
American Express (AMEX)	340000000004001	Exitoso (autenticación correcta)
Discover	6573700000000009	Exitoso (autenticación correcta)
Mastercard	5591390000000504	Exitoso (autenticación correcta)
Visa	4900490000000501	Exitoso (autenticación correcta)

Errores simulados (autenticación fallida)

Marca	Número de tarjeta	Escenario / Resultado
American Express (AMEX)	340000000004019	Estado: N (Autenticación fallida / consulta 3DS fallida)
Discover	6599999900000313	Estado: N (Autenticación fallida)
Mastercard	5591390000000520	Estado: N (Autenticación fallida)
Visa	4900490000000519	Estado: N (Autenticación fallida)

---

Conjunto #2: Pruebas de pasarela de doble escenario (paymentEntity: 2 y 4)

Usa este conjunto al probar cuentas configuradas con paymentEntity: 2 y paymentEntity: 4.

Marca	Escenario	Número de tarjeta
Visa	Exitoso	4000000000002503
Mastercard	Exitoso	5200000000002151
Visa	Fallido	4000000000002420
Mastercard	Fallido	5200000000002664

---

Conjunto #3: Simulador estándar y escenarios de error específicos (paymentEntity: 1 y 3)

Usa este conjunto al probar cuentas configuradas con paymentEntity: 1 y paymentEntity: 3 para probar casos límite como rechazos generales de tarjetas, fondos insuficientes y expiración de tarjeta.

Transacciones exitosas

Marca	Número de tarjeta
Visa	4111111111111111
Mastercard	5555555555555555
Maestro	6771290000000001

Simulación de escenarios de error

Escenario	Número de tarjeta / Condición	Detalles
Tarjeta rechazada (general)	4000000000000002	Simula un rechazo genérico del emisor.
Fondos insuficientes	4111111111111002	Simula una transacción rechazada por saldo insuficiente.
Tarjeta expirada	Cualquier número de tarjeta de prueba válido	Introduce una fecha de expiración en un mes/año pasado (por ejemplo, 01/20).

---

Manejo de callbacks y eventos webhook

Consejo de pruebas

No necesitas disparar individualmente cada permutación posible de error de pago (por ejemplo, fondos insuficientes, error de autorización, timeout del desafío 3DS). En su lugar, asegúrate de que tus manejadores de callback y webhook procesen correctamente los esquemas de payload estándar para estados completados y fallidos.

Cuando cambia el estado de un pago con tarjeta o falla, TropiPay envía un evento de callback a tu endpoint configurado (notificationUrl o objetivo de webhook suscrito).

Ejemplo: Callback de cambio de estado / fallo de pago

A continuación se muestra un ejemplo del evento de callback recibido cuando ocurre una transición de estado de pago con tarjeta o falla:

{
  "signature": "b2740b505314ef1577235b5c8d484e312b64ed3fade27324fe23ef1bb1f8f4cd",
  "event_name": "payment_in_state_change",
  "userId": "10951e80-6218-11ef-9e2f-7f00b2bfc1f3",
  "date": 1786830266966,
  "uuid": "ae4c6fdf-449d-496a-9622-03b863e366e6",
  "data": {
    "stateStr": "processing",
    "state": 1,
    "id": 5091118,
    "reference": "TAB1508260286",
    "bankOrderCode": "636452502154",
    "conceptTransfer": null,
    "service": 2,
    "movementType": 2,
    "destinationAmount": "4976"
  }
}

Atributos del payload de callback

Campo	Tipo	Descripción
signature	string	Firma HMAC-SHA256 para verificar que el payload se originó en TropiPay.
event_name	string	Nombre del evento despachado (por ejemplo, payment_in_state_change).
userId	string	Identificador único del usuario comerciante de TropiPay.
date	number	Timestamp Unix (en milisegundos) de cuándo se despachó el callback.
uuid	string	UUID único de seguimiento de la notificación.
data.id	number	ID interno de la transacción/reserva.
data.reference	string	Tu referencia de orden interna proporcionada durante la creación del pago.
data.bankOrderCode	string	Código de seguimiento de orden bancaria de TropiPay.
data.state	number	Estado numérico de la transacción.
data.stateStr	string	Cadena legible del estado (por ejemplo, processing, completed, failed).
data.destinationAmount	string	Monto de la transacción liquidado.

Mejores prácticas para pruebas

1. Devuelve siempre HTTP 200 inmediatamente: Tu endpoint receptor de webhook debe responder con un estado HTTP 200 OK inmediatamente al recibirlo para acusar recibo.
2. Procesa de forma asíncrona: Aplaza las actualizaciones de base de datos, cumplimientos de pedidos y llamadas a APIs externas a colas en segundo plano después de devolver la respuesta 200.
3. Valida firmas: Calcula y verifica siempre la firma del payload usando tu clave secreta para prevenir suplantaciones.
4. Usa herramientas de inspección de webhooks: Herramientas como Webhook.site o ngrok facilitan inspeccionar payloads y depurar callbacks durante las pruebas en sandbox.