Pasarela de pagos de lotería: webhooks, reintentos y reembolsos
Una integración de pasarela de pagos para lotería está lista cuando los pagos, los apuntes del monedero y los informes de liquidación coinciden, incluso después de reintentos, timeouts, reembolsos y notificaciones retrasadas. Una pantalla de pago correcto no demuestra que el operador haya recibido fondos o acreditado una sola vez la cuenta adecuada. Esta guía […]
Una integración de pasarela de pagos para lotería está lista cuando los pagos, los apuntes del monedero y los informes de liquidación coinciden, incluso después de reintentos, timeouts, reembolsos y notificaciones retrasadas. Una pantalla de pago correcto no demuestra que el operador haya recibido fondos o acreditado una sola vez la cuenta adecuada.
Esta guía describe requisitos de integración, no campos reales de la API de WhiteLotto ni soporte garantizado de un procesador concreto. La elegibilidad, los productos admitidos y las condiciones comerciales deben confirmarse por separado. Consulta la guía del stack de pagos de lotería para entender el alcance operativo y los costes.
Distingue los registros del procesador, monedero y finanzas
Acuerda qué sistema controla el intento de pago, el resultado final del proveedor, el apunte del monedero, la instrucción de retirada y la conciliación contable. Relaciona sus identificadores sin tratarlos como equivalentes. Define importes, moneda, redondeo y comisiones en cada frontera.
| Situación | Comportamiento requerido | Evidencia a conservar |
|---|---|---|
| Creado o pendiente | No confundir una operación iniciada con un ingreso completado. | ID de operación, referencia del proveedor y estado actual. |
| Autorizado o capturado | Aplicar la regla acordada de abono para el método de pago real. | Evento verificado y apunte contable vinculado. |
| Respuesta incierta | Determinar el resultado original antes de crear otra operación. | Historial de consultas o reintentos y resolución final. |
| Reembolso o reversión | Vincular el ajuste al pago original y evitar efectos duplicados. | Referencia del ajuste, importe, motivo y aprobación. |
| Disputa o diferencia de liquidación | Crear una excepción con responsable y respuesta de finanzas. | Informe del proveedor, registro interno y trazabilidad de resolución. |
Diseña los webhooks para repetición y retrasos
Verifica el origen del evento con el mecanismo documentado por el proveedor antes de confiar en su contenido. Valida cuenta, pago, importe y moneda referenciados. Guarda el evento u operación aceptados antes de devolver la respuesta que confirma la entrega. Procesa el trabajo prolongado mediante una ruta recuperable.
No supongas que los eventos llegan una sola vez ni ordenados. Stripe documenta verificación de firmas, duplicados y ausencia de garantía de orden. Adyen documenta sus reglas de confirmación y tratamiento de duplicados. Son referencias específicas de esos proveedores, no evidencias de una integración de WhiteLotto con ellos.
Elige claves de deduplicación y reglas de transición según el contrato real. Un nuevo identificador de entrega puede representar el mismo evento de negocio. Un evento retrasado no debe hacer retroceder una operación resuelta. Mantén fallos visibles en una cola de excepciones y ofrece una repetición controlada.
Define reintentos seguros y resultados inciertos
Supongamos que el proveedor completa un ingreso pero la plataforma no recibe la respuesta. Iniciar otro pago puede cobrar al jugador dos veces. Reutiliza la referencia soportada o el mecanismo de idempotencia y consulta el resultado original.
La documentación de idempotencia de Stripe muestra cómo un proveedor define el comportamiento de repetición. No traslades sus plazos de conservación ni su semántica de errores a otro procesador. Tu contrato necesita el periodo de protección, la respuesta ante contenido conflictivo y la recuperación después de ese periodo.
Prueba concurrencia además de repetición: dos procesos pueden recibir el mismo evento simultáneamente. Una protección que solo funciona en una sesión de navegador no basta para un registro contable compartido.
Concilia movimientos brutos y diferencias
Relaciona operaciones del proveedor con apuntes del monedero e informes de liquidación. Explica por separado comisiones, reembolsos parciales, disputas, diferencias de cambio y desfases temporales. Los depósitos no son ventas de boletos; un ingreso correcto no demuestra que se haya aceptado una compra posterior.
Finanzas debe investigar cada importe no conciliado mediante referencias permitidas, marcas temporales e historial. Utiliza el marco de KPI para mostrar importe y antigüedad pendientes sin ocultar diferencias opuestas al compensarlas.
Checklist de aceptación de pagos
- Prueba ingresos correctos, rechazados, cancelados y pendientes.
- Simula la pérdida de la primera respuesta y consulta o reintenta de forma segura la operación original.
- Envía eventos de prueba duplicados, concurrentes, retrasados y desordenados.
- Rechaza firmas inválidas, monedas erróneas y referencias de otras cuentas.
- Prueba reembolsos completos y parciales, retiradas fallidas y diferencias de conciliación.
- Comprueba que los secretos no aparecen en código del navegador ni registros sin restricciones.
Ejecuta estos casos en sandboxes autorizados con datos ficticios. La guía de pruebas de pagos de OWASP es una referencia para lógica de negocio y temporización. Documenta resultados financieros en el paquete UAT; este checklist no autoriza pagos reales.
Preguntas frecuentes sobre integración de pagos
¿Una redirección del navegador debe abonar el monedero?
La decisión necesita evidencia autoritativa en el servidor según el contrato. Una página de éxito por sí sola no aporta esa evidencia.
¿La integración garantiza que el proveedor acepte el negocio de lotería?
No. Elegibilidad, aprobación del mercado o producto y alta comercial son decisiones separadas del proveedor y los responsables.
Comparte métodos de pago, mercados y requisitos de liquidación con WhiteLotto. Empieza por la arquitectura de integración. CONTACTO.