Por qué la misma llamada llega dos veces
Tomemos el caso común. WGC llama a su Callback URL con una apuesta, usted debita al jugador y responde, y su respuesta se pierde en el camino. Desde el punto de vista de WGC, la operación es desconocida: no sabe si usted la registró. Un proveedor de juegos también puede reintentar una apuesta tras un fallo de su propio lado. En ambos casos la repetición lleva el mismo transactionId. Un manejador que la trate como una apuesta nueva debita al jugador dos veces, y la disputa que sigue es costosa para todos.
Por eso, en la billetera de WGC, esta regla que afecta directamente al dinero del jugador no es un deseo sino una condición de la integración: writeBet se registra una sola vez por transactionId, y una llamada repetida no debita dos veces y devuelve el mismo saldo.
Quién repite qué
Los dos comandos se repiten de maneras distintas, y conviene mantenerlos separados.
writeBetlo repite el proveedor del juego, no WGC, y la repetición llega con el mismotransactionId. WGC responde una repetición de una operación que ya liquidó a partir de lo que guardó. Solo cuando el intento anterior nunca le llegó a usted, la llamada sale de nuevo, con el mismotransactionId.rollbacklo repite WGC, según un calendario fijo que no es un ajuste: alrededor de un minuto después de la respuesta que faltó, luego a los 5, 15, 60, 360 y 1440 minutos, y después una vez al día hasta que pasen 30 días desde la apuesta. Después de eso los reintentos se detienen y el personal de WGC resuelve el caso con usted.
Guarde sus propios registros de cada transacción, por transactionId, durante al menos 30 días, porque un rollback puede llegar hasta 30 días después de la apuesta.
Las reglas de un `writeBet` seguro
- Haga único el
transactionIden su base de datos. La manera fácil de ser idempotente es una clave única: la segunda inserción falla, y usted responde con lo que guardó para la primera. - Responda una repetición exactamente como respondió la primera vez. El mismo saldo, sin un segundo débito. La repetición de un rechazo es el mismo rechazo.
- Maneje dos llamadas idénticas en el mismo instante. Un esquema de comprobar y luego escribir, en pasos separados, puede dejar pasar a ambas. La clave única, o un bloqueo, decide quién va primero.
- Rechace un
kindque no conozca.kindesplayorefund, yjackpotsolo cuando su gerente haya activado los jackpots para su cuenta. - Ignore los campos que no conozca. Pueden aparecer campos nuevos.
A continuación se muestra una repetición. Ambas llamadas llevan el mismo transactionId, y ambas reciben la misma respuesta.
{ "command": "writeBet", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "roundId": "3f1c2a64-8d0b-4e57-9b7a-5c2e1d0f9a41", "gamePublicId": "sweet-bonanza-1", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "kind": "play", "requestId": "req_…", "timestamp": "2026-10-12T10:15:01.000Z" }
← { "ok": true, "balance": 122.45 }
(the same call again)
← { "ok": true, "balance": 122.45 }Las reglas de un `rollback` seguro
Un rollback le pide revertir una apuesta por completo: la apuesta vuelve al jugador y la ganancia se retira. También es idempotente: el mismo transactionId de nuevo no debe revertir dos veces.
{ "command": "rollback", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "reason": "unknown_outcome", "requestId": "rb:5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b:1", "timestamp": "2026-10-12T10:16:01.000Z" }
← 200 { "balance": 123.45 } # taken
← 200 { "ok": false, "error": "insufficient_funds" } # a refusal: WGC asks again
← 404, 405, or { "error": "unknown_command" } # not implemented: not a failure- Si nunca registró ese
transactionId, no cambie nada y responda de todos modos con el saldo. - WGC cuenta un rollback como aceptado solo con un HTTP 2xx y un saldo legible. Un rechazo, un tiempo de espera o una respuesta ilegible es un rechazo, y el calendario continúa, por lo que un rollback repetido también debe responderse con un 2xx.
- Un 404, un 405 o
unknown_commandle dice a WGC que usted no implementa rollbacks. WGC deja entonces de repetir, y el personal resuelve el caso con usted. - Un
writeBetque llega después de su propio rollback debe rechazarse, como hacen los manejadores de ejemplo públicos.
Tiempos de espera y qué cuenta como respuesta
WGC espera 3 segundos su respuesta, y una respuesta se toma como dada solo con un estado de 200 a 299. Un 500 con {"ok":true} en el cuerpo no cuenta: la operación queda desconocida y sigue un rollback. Un rechazo es una respuesta normal: { "ok": false, "error": "insufficient_funds" } con estado 200. Las redirecciones no se siguen; por eso responda directamente desde la dirección de Callback, sin redirigir a otra.
Dos plazos más cortos protegen al jugador. Una apuesta que esperó más de 1,5 segundos dentro de WGC no se le envía, y no se quita nada. Una apuesta que usted aceptó y cuya respuesta no pudo llegar al proveedor del juego en 4,5 segundos se cancela de inmediato mediante un rollback. Las ganancias, los jackpots y los reembolsos no tienen ese plazo: siempre le llegan.
Cada llamada va firmada. Compruebe la firma sobre el cuerpo sin procesar antes de analizarlo, compare en tiempo constante y rechace una llamada cuya marca de tiempo tenga más de 5 minutos.
Abrir una sesión es otro contrato
No traslade las reglas de la billetera a POST /v1/sessions. Allí, el encabezado opcional Idempotency-Key vive 24 horas: la misma clave y el mismo cuerpo devuelven la misma respuesta sin una nueva llamada al proveedor del juego, y la misma clave con otro cuerpo es invalid_request. Mientras una sesión está abierta, una segunda apertura del mismo jugador, juego, moneda y modo devuelve esa sesión y el mismo enlace de lanzamiento. Pruebe ambos contratos como casos separados; así distingue con facilidad de cuál viene un error.
Demuéstrelo antes del juego real
- Ejemplos públicos y una autocomprobación. Los manejadores en Node.js, PHP y Python y el script
wallet-check.mjsson públicos. La autocomprobación envía dos llamadaswriteBetidénticas a la vez y espera un solo débito y la misma respuesta para ambas. - La prueba de integración. En el back office ejecuta 14 comprobaciones de su billetera. Tres de ellas tratan de repeticiones: el mismo
transactionIdde nuevo no se debita dos veces, dos apuestas iguales en el mismo instante debitan una sola vez, y un rollback repetido no devuelve nada más y se acepta. - El juego de prueba. Una clave de prueba abre WGC Test Slot, donde cada giro hace dos llamadas reales a su Callback URL con
"test": true, sin dinero. Una opción para perder la respuesta deja la operación desconocida, y alrededor de un minuto después llega unrollback. - Integration check. Muestra cada llamada y respuesta en vivo. Después de una ejecución, el estado de una operación y de su rollback puede leerse con
GET /v1/transactions/{transactionId}.
Vea el modo demo y de prueba, los pasos de integración y la descripción general de la API de casino; el contrato está en la página de billetera seamless.