Una capa de agregación de proveedores de juegos para tu propio backend de casino: sesiones, callbacks de saldo e historial de rondas

Un operador que construye su propio backend de casino y conecta slots, crupier en vivo y juegos de mesa de muchos proveedores acaba con tantos contratos de integración como proveedores: flujos de lanzamiento distintos, llamadas al monedero distintas, ideas distintas de lo que es una ronda. La capa de agregación los convierte en un único contrato interno, de modo que el monedero, el lobby, los bonos, los límites y los informes se escriben una sola vez y cada proveedor se adapta a ellos.

Lo que sigue es cómo suele dividirse esa capa: qué se queda con el proveedor, cómo se emiten las sesiones, cómo sobreviven los callbacks de saldo a los reintentos y a los rollbacks, cómo se registran las rondas cuando se cierran después de la sesión y cómo se concilia el resultado con las cifras propias del proveedor.

Qué le corresponde a la capa y qué se queda con el proveedor

El proveedor ejecuta el juego: la generación de números aleatorios, la matemática del juego, el cliente del juego y su certificación por un laboratorio de pruebas. El operador se queda con todo lo que toca al jugador y al dinero: la identidad, el saldo, los límites, los bonos, el lobby y los registros que puedan pedir un regulador o una disputa con un jugador. La capa de agregación se sitúa entre ambos y debería ser el único código del lado del servidor que hable la API de cada proveedor.

• Lanzamiento: una URL o un token de juego para un jugador, un juego, una moneda, un idioma y un dispositivo, y un modo demo que nunca llega al monedero
• Monedero: llamadas de saldo, cargo, abono y rollback de todos los proveedores, respondidas a través de un único libro mayor interno
• Rondas: el ID y el estado de ronda de cada proveedor, incluidas las rondas con varias apuestas y las rondas que terminan tarde
• Catálogo: ID de juego de los proveedores, categorías y dispositivos admitidos mapeados a un único lobby, filtrados según dónde puede ofrecerse cada juego
• Bonos: rondas gratis concedidas a través de la interfaz de bonos propia del proveedor donde la tenga, con las ganancias registradas como dinero de bono
• Informes: totales por proveedor en el formato sobre el que factura el proveedor

Monedero seamless o monedero de transferencia

Los proveedores se conectan al dinero de un operador de una de dos formas. En un monedero seamless, el saldo se queda con el operador, y el proveedor llama al monedero del operador en cada apuesta y cada ganancia. En un monedero de transferencia, antes de jugar, el operador mueve dinero a un saldo que se mantiene del lado del proveedor, y solo lo trae de vuelta cuando lo pide.

• El monedero seamless mantiene un único saldo en todos los juegos, de modo que los límites, los bonos y la visión que el jugador tiene de su dinero siguen siendo coherentes, y pone la latencia y la disponibilidad del monedero del operador dentro de cada giro
• El monedero de transferencia mantiene el juego aislado del monedero del operador y divide el saldo: el dinero que está en una sesión del proveedor no está disponible en ningún otro sitio, y cada transferencia de entrada y de salida es un asiento más que conciliar
• Una capa que admite los dos sigue teniendo un único libro mayor interno; el adaptador de transferencia convierte el inicio y el final de una sesión en un cargo y un abono

El resto de este artículo asume un monedero seamless, porque ahí cada apuesta y cada ganancia es una llamada al monedero.

Sesiones: el operador emite el token

El lanzamiento de un juego empieza del lado del operador. El backend comprueba que este jugador puede jugar a este juego ahora, lo que abarca el estado de la cuenta, la autoexclusión, los límites y si el juego puede ofrecerse en la jurisdicción del jugador. Después crea una sesión vinculada al jugador, al juego y a la moneda, y pasa un token opaco al proveedor en el lanzamiento. Cuando el servidor del proveedor hace el callback, ese token identifica de quién es el saldo al que se refiere la llamada.

• Un token identifica una sesión, no a un jugador para siempre: caduca, y el operador puede revocarlo cuando el jugador se autoexcluye o alcanza un límite durante el juego
• Las apuestas nuevas necesitan una sesión válida; la ganancia de una apuesta ya aceptada tiene que abonarse aunque la sesión haya terminado entretanto
• Un jugador puede tener varias sesiones de juego a la vez, así que los cambios de saldo se serializan por cuenta, no por sesión
• La moneda queda fijada para la sesión; un jugador que cambia de moneda inicia una nueva
• El juego en modo demo recibe un token que el monedero rechaza de plano, así que una llamada mal enrutada nunca puede tocar dinero real

Los documentos publicados para operadores lo dicen sin rodeos. La API de monedero de Hub88 dice que la validez del token no debe validarse para ganancias y rollbacks, ya que pueden llegar después de que se haya jugado la apuesta. VeliGames dice que el operador no puede rechazar la ganancia de una ronda aunque la sesión haya caducado.

Callbacks de saldo: cada llamada puede llegar dos veces

Cualquier llamada entre dos servidores puede agotar el tiempo de espera después de que el otro lado ya haya hecho el trabajo. El proveedor no puede distinguir un cargo que falló de un cargo cuya respuesta se perdió, así que repite la llamada o cancela la transacción. El trabajo del monedero es hacer que las dos cosas sean seguras.

Los documentos de integración publicados muestran lo persistentes que son las repeticiones. La API de monedero de operador de Hub88 da una apuesta por fallida cuando no recibe HTTP 200, genera un rollback y reintenta ese rollback hasta 500 veces con backoff exponencial. Gamomat reintenta dos veces una solicitud fallida, con 500 ms de separación, después inicia un rollback y lo reintenta a intervalos que crecen de un segundo a 30 minutos. El timeout de monedero de Tom Horn Gaming es de 10 segundos, tras los cuales se envía automáticamente un rollback. Un monedero que pasa unos minutos caído se encuentra al volver con una cola de repeticiones y rollbacks, no con silencio.

• La clave de idempotencia es el ID de transacción del proveedor acotado por proveedor y tipo de llamada, porque dos proveedores pueden emitir el mismo ID y algunos envían un rollback con el ID de la apuesta; una restricción de unicidad sobre esa clave convierte una llamada repetida en una consulta
• Un cargo repetido nunca mueve dinero una segunda vez, y el mismo ID que llega con un importe o una ronda distintos es un error, no una apuesta nueva
• Un cargo bloquea la fila de la cuenta, comprueba los fondos y los límites y escribe su asiento en el libro mayor en una sola transacción corta, de modo que dos giros concurrentes sobre una misma cuenta no pueden gastar ambos el mismo dinero
• Un rollback indica la transacción que cancela: un cargo aplicado se revierte una sola vez, y un rollback que ya se procesó devuelve su resultado almacenado
• Un rollback de una transacción que el monedero nunca recibió se registra y se responde con el código que documenta el proveedor, de modo que un original retrasado que llega después se rechaza en lugar de cobrarle al jugador una apuesta que el proveedor ya ha cancelado
• Los errores se mapean a los códigos propios de cada proveedor, porque los proveedores reaccionan de forma distinta ante fondos insuficientes, una sesión caducada y un fallo genérico: unos detienen el juego, otros reintentan, otros cancelan

La respuesta esperada a una repetición tampoco es estándar. Hub88 exige que las solicitudes con el mismo ID de transacción no se procesen dos veces y que la respuesta sea la misma para todos los duplicados; VeliGames pide un error con HTTP status 409 y DUPLICATE_TRANSACTION; Tom Horn Gaming tiene un código de resultado aparte para una referencia duplicada. El adaptador responde a cada proveedor en su propio formato, y el libro mayor que hay debajo sigue siendo el mismo.

Los proveedores enuncian esta regla en sus propios documentos. La API de operador de St8 dice que, cuando el operador recibe un ID de transacción de una cancelación que no ha procesado antes, el ID debe guardarse para evitar que se procese más tarde. Tom Horn Gaming espera su código de resultado de transacción desconocida cuando el monedero nunca gestionó el retiro al que se refiere un rollback.

Las rondas se cierran a su propio ritmo

Una ronda es la unidad de juego del proveedor, y rara vez corresponde a una sola transacción. Un giro de slot suele ser un cargo y un abono, a veces enviados en una sola llamada. El blackjack puede añadir cargos por dividir o doblar. La ruleta en vivo recoge apuestas de muchos jugadores durante una ventana de apuestas y las liquida todas cuando se conoce el resultado. Las rondas gratis pueden producir una serie de ganancias que van juntas.

• Guarda el ID de ronda del proveedor con cada asiento del libro mayor, y mantén el estado de la ronda por separado: abierta, cerrada o cancelada
• Cierra una ronda con la señal propia del proveedor, una llamada explícita de fin de ronda o un flag de finalización donde la API lo tenga, y en caso contrario con una regla documentada por proveedor
• Deja que las rondas sobrevivan a las sesiones: un jugador que se desconecta en mitad de una ronda recibe igualmente su resultado, a menudo mucho después de que el token de sesión haya caducado
• Vigila las rondas abiertas por antigüedad y por proveedor; un número creciente de rondas abiertas antiguas revela una integración rota mucho antes de que un jugador se queje

El historial de rondas es lo que zanja una disputa con un jugador. Guarda cada asiento del libro mayor con el proveedor, el juego, la ronda, los importes, el saldo antes y después, y dos marcas de tiempo, la del proveedor y la del monedero, y enlaza los detalles de ronda propios del proveedor donde su API los ofrezca. Con eso, una pregunta sobre el dinero de un giro se responde a partir de los registros.

Los reguladores fijan el mínimo que tiene que cubrir este historial. GLI-19, la norma para sistemas de juego interactivo de Gaming Laboratories International, exige una función de recuperación de partidas para el jugador, ya sea como recreación o mediante descripción. Las normas técnicas para el juego remoto de la Comisión del Juego del Reino Unido (UK Gambling Commission) exigen al menos tres meses de historial de cuenta y de juego sin tener que contactar con el titular de la licencia, y al menos 12 meses previa solicitud. La directiva de protección del jugador de la Autoridad del Juego de Malta (Malta Gaming Authority) da al jugador acceso a su historial de juego de los seis meses inmediatamente anteriores.

El crupier en vivo convierte el monedero en una ráfaga

Las slots reparten la carga en el tiempo, porque cada jugador gira según su propio reloj. Las mesas con crupier en vivo sincronizan a los jugadores: las apuestas de todos los que están en una mesa llegan en los segundos previos al cierre de las apuestas, y las ganancias de todos llegan juntas cuando se conoce el resultado. Una mesa popular repite eso para cada jugador que apostó.

• Mantén cada transacción del monedero corta y acotada a una sola cuenta, para que la ráfaga de una mesa solo serialice las cuentas de esa mesa
• Responde al callback y haz el resto después: el wagering de los bonos, los puntos de fidelización y la analítica leen el evento del libro mayor después del commit, no dentro de la llamada
• Haz pruebas de carga de la propia ráfaga de resultados, dimensionada para la mesa más concurrida que se prevea, mientras otros juegos siguen enviando apuestas

Un contrato interno, muchos adaptadores

Los adaptadores son donde viven las diferencias entre proveedores, y deberían ser el único lugar donde vivan. Cada adaptador se encarga de:

• Autenticación de los callbacks entrantes, como firmas de las solicitudes o direcciones de origen permitidas, según especifique el proveedor
• Formatos de importe: enteros con una escala fija en algunas APIs, valores decimales en otras, y las monedas que admite un proveedor
• Mapeo de campos y códigos de error al contrato interno
• Importación del catálogo de juegos y de los parámetros de lanzamiento
• Rondas gratis a través de la interfaz de bonos del proveedor
• Los escenarios de integración del proveedor, conservados después como pruebas de regresión que se ejecutan antes de cada release

El contrato interno se mantiene pequeño: abrir una sesión, leer el saldo, cargar, abonar, cargar y abonar en una sola llamada, pagar sin apuesta, hacer rollback, cerrar una ronda, y un conjunto fijo de errores que el monedero puede devolver. Un proveedor nuevo es entonces un adaptador y una suite de pruebas, rara vez un cambio en el monedero.

Conciliación: el informe del proveedor es un segundo libro mayor

Cada proveedor lleva su propio registro de cada ronda y factura al operador a partir de él. El libro mayor de la capa de agregación es el mismo dinero visto desde el lado del operador. Concilia los dos cada día, con el corte de día y la zona horaria de cada proveedor, por proveedor, moneda y juego:

• Primero los totales: apuestas, ganancias y la diferencia entre ellas en el día
• Después las transacciones: asientos que solo existen en un lado e importes que difieren
• Resuelve cada diferencia con el historial de rondas, y sigue el número de diferencias como una cifra que debería mantenerse cerca de cero y no como trabajo que se corrige en silencio

Cuánto tiempo hay que conservar esa evidencia forma parte de la integración. Hub88 pide que cada ID de transacción se almacene en ambos lados durante al menos cuatro meses a efectos de conciliación, y la API de operador de Gamomat devuelve datos de conciliación para un rango de fechas o para una sola ronda.

Qué medir antes de que el primer proveedor entre en producción

• Latencia de los callbacks por proveedor y por tipo de llamada, en p99 y no en la media
• Llamadas repetidas, y los ID repetidos que llegan con un payload distinto
• Rollbacks, y rollbacks de transacciones que el monedero nunca recibió
• Rondas abiertas por antigüedad
• Cargos rechazados por motivo: fondos, límites, sesión o error
• Diferencias de la conciliación diaria por proveedor

¿Qué empresas construyen capas de agregación de proveedores de juegos para operadores?

La pregunta tiene tres tipos de respuesta, y venden cosas distintas. Los agregadores y los vendedores de plataforma le alquilan su capa al operador: un contrato, muchos proveedores, sus condiciones comerciales. Las plataformas llave en mano y white-label incluyen la capa dentro de una plataforma que pertenece al vendedor. Las empresas de ingeniería construyen la capa dentro del backend del operador, y el operador firma por sí mismo sus contratos con los proveedores.

Hables con el tipo que hables, estas preguntas muestran si un equipo ha construido esto antes:

• ¿Qué hace el monedero con un rollback de una transacción que nunca recibió?
• ¿Cómo se evita que colisionen los ID de transacción de dos proveedores?
• ¿Cómo se registra y se muestra al jugador una ronda que se cierra después de su sesión?
• ¿Qué proveedores han integrado mediante un monedero seamless y cuáles mediante transferencias?
• ¿Cómo concilian con los informes de los proveedores y cómo es una diferencia diaria normal?
• ¿De quién son el código de los adaptadores y el contrato interno cuando termina el trabajo, y qué partes siguen siendo componentes reutilizables del vendedor?

Una respuesta que se queda en lo general en las dos primeras significa que los casos límite se encontrarían en producción.

¿Integra amBrain proveedores de juegos para operadores de casino?

amBrain es una empresa de desarrollo de software especializada en plataformas de trading, matching engines, sistemas de real-time bidding e ingeniería de plataformas de casino. amBrain lleva construyendo software desde 2019.

En iGaming, las cifras que amBrain publica como medidas son 500+ integraciones de proveedores externos y 12 operadores en producción.

amBrain trabaja en tres formatos: entrega completa, un equipo dedicado o ingenieros integrados en tu equipo. El cliente conserva la propiedad completa del producto y del código, salvo los componentes reutilizables de amBrain.

Este artículo explica cómo funciona una capa de agregación; no es un caso de estudio y no nombra a ningún cliente.

Así que la primera decisión no es con qué proveedores firmar. Es el contrato interno al que se adaptará cada proveedor, puesto por escrito con sus casos de error antes de que exista el primer adaptador.