Billetera única vs billetera de transferencia

De un vistazo

Billetera única (seamless)

En el modelo de billetera única (seamless), su sistema es la billetera. Cuando un jugador realiza una apuesta, la API de SSG llama a su endpoint de callback, usted modifica el saldo en su propio libro mayor y responde con el nuevo saldo. Ningún fondo sale de su base de datos.

Flujo de llamadas

1. Inicio: su backend solicita a SSG una URL de juego con un ID de jugador y un token de sesión.
2. Apuesta: por cada ronda, SSG llama a debit con un txId único. Usted verifica los fondos, registra la fila en el libro mayor y devuelve el nuevo saldo.
3. Premio: SSG llama a credit con el pago (que puede ser cero) de la misma ronda.
4. Fallo: si una llamada agota el tiempo de espera, SSG reintenta con el mismo txId y, al superar el límite de reintentos, envía rollback.

Métodos de callback (ilustrativo)

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

Reglas que debe cumplir su servicio de billetera

Idempotencia

Un debit o credit repetido con el mismo txId debe devolver el resultado original y no volver a mover dinero. Aplíquelo con un índice único en txId.

Escritura atómica en el libro mayor

Verifique el saldo, inserte la fila del libro mayor y actualice el saldo en una sola transacción de base de datos, de modo que dos apuestas simultáneas nunca generen sobregiro.

Rollback antes del debit

Puede llegar un rollback para un txId que nunca vio porque el debit original agotó el tiempo de espera. Almacene un tombstone para rechazar un debit tardío con ese txId.

Presupuesto de latencia

Apunte a un p99 inferior a 500 ms incluyendo la red. Limite la ruta de callback a una lectura indexada y una escritura, y mantenga las consultas de reportes fuera de ella.

Formato de dinero

Trate los montos como cadenas decimales o unidades menores enteras. No use nunca punto flotante y valide la moneda contra la cuenta del jugador.

Bonos y giros gratis

Un giro gratis es un débito de 0 seguido de un crédito por la ganancia. Mantenga los saldos promocionales separados del saldo en efectivo en su libro mayor.

Seguridad

Verifique una firma HMAC-SHA256 sobre la solicitud canónica, rechace marcas de tiempo vencidas, autorice solo las IP de origen de SSG y exija TLS 1.2 o superior.

Conciliación

Compare los reportes diarios de rondas de SSG con su libro mayor por roundId. Las diferencias señalan callbacks omitidos o rollbacks.

Billetera de transferencia

En el modelo de billetera de transferencia, el proveedor mantiene un saldo de juego por cada jugador. Su backend mueve los fondos antes de jugar y los retira después. Durante el juego no hay callbacks a su sistema, por lo que solo necesita llamadas REST salientes.

Flujo de llamadas

1. Transferencia de entrada: su backend llama a transferIn con un txId único y el monto. El resultado es PENDING o SUCCESS.
2. Juego: inicie el juego. Todas las apuestas y ganancias modifican el saldo del lado del proveedor sin callbacks hacia usted.
3. Transferencia de salida: cuando el jugador se retira, llame a transferOut por el saldo completo y acredítelo en su propio libro mayor con SUCCESS.
4. Resultado desconocido: si una llamada de transferencia agota el tiempo de espera, consulte getTransferStatus con el mismo txId antes de hacer cualquier otra cosa.

Métodos de API (ilustrativo)

Reglas que su backend debe seguir

Un txId por intención

Genere el txId antes de la primera llamada y reutilícelo en cada reintento. No cree un nuevo txId hasta conocer el estado del anterior.

Debite primero su libro mayor

En una transferencia de entrada, reserve el monto en su libro mayor antes de llamar a SSG y luego confírmelo o libérelo cuando el estado sea final.

Barrido de saldos varados

Ejecute un proceso que encuentre jugadores con saldo de juego y sin sesión activa, y lo transfiera de salida. Esto cubre a los jugadores que cierran el navegador a mitad de sesión.

Apuestas y reportes

Como no ve las apuestas en vivo, calcule el volumen apostado, el rollover de bonos y los límites de riesgo a partir de los reportes de rondas obtenidos de SSG, no de los callbacks.

Conciliación

Concilie cada transferencia de entrada y salida con los registros de SSG por txId y genere una alerta ante cualquier PENDING que supere su tiempo de espera.

Seguridad

Firme las solicitudes con HMAC-SHA256, llame solo mediante TLS 1.2 o superior, guarde las claves de API en un almacén de secretos y restrinja qué servidores suyos pueden llamar a SSG.

Escenarios de fallo

Cuál elegir

Muchos operadores comienzan con billetera de transferencia para salir en vivo y luego pasan a billetera única cuando su propio servicio de billetera está listo. Consúltenos cómo se escalona el cambio.

Lista de verificación de integración

• Índice único en txId y manejadores idempotentes para cada llamada que mueva dinero
• Verificación de firma HMAC, tolerancia de marca de tiempo y lista de IP permitidas
• Montos seguros en decimales y validación de moneda
• Pruebas de tiempo de espera, reintento y rollback en el sandbox, incluido un reintento tardío
• Proceso diario de conciliación por roundId (única) o txId (transferencia)
• Monitoreo y alertas: latencia de callbacks, tasa de errores, transferencias pendientes, saldos varados