API v1 · Operadores

Integração de operadores

Os seus jogadores jogam os nossos jogos e o saldo continua na sua carteira. Seu servidor lista os jogos disponíveis, abre a sessão e publica um endpoint que recebe os lançamentos de cada rodada.

URL base
https://games.bichostars.net
Autenticação
HMAC-SHA256 por pedido
Formato
JSON sobre HTTPS
Moeda
BRL, em unidades de R$ 0,0001
01

Visão geral

Nós decidimos o resultado de cada rodada e pedimos à sua carteira que debite a aposta e credite o prêmio. O jogador só vê o resultado depois que a sua carteira confirma.

Você chama

Abertura de sessão

POST /backend/v1/operator/sessions

Uma vez por jogador e jogo. Devolve a URL que abre o jogo.

Você publica

Callback de carteira

POST na sua URL HTTPS

Recebe os eventos de cada rodada: bet, prize, reconciliation e refund.

Uma rodada, do começo ao fim

  1. Seu servidor→API

    Abre a sessão com o jogador, o jogo e o saldo atual. Recebe a launch_url.

  2. Seu servidor→Jogador

    Abre a launch_url no navegador do jogador. Daqui em diante o jogo fala direto com a nossa API.

  3. API→Sua carteira

    O jogador gira e você recebe bet. Debita a aposta e responde com o novo saldo.

  4. API→Sua carteira

    Se a rodada pagou, você recebe prize. Credita o prêmio e responde com o novo saldo.

  5. API→Jogador

    O resultado aparece na tela, com o saldo que a sua carteira informou.

  6. API→Sua carteira

    Você recebe reconciliation, que fecha a rodada com os totais. Toda rodada termina com ela.

O que implementar, nesta ordem

  1. Peça as credenciais à nossa equipe.
  2. Escreva a rotina de assinatura e confira com os vetores de teste.
  3. Consulte o catálogo para exibir os jogos e suas capas.
  4. Abra uma sessão e leve o jogador para o jogo.
  5. Publique o endpoint de callback.
  6. Trate as repetições e o refund.
  7. Passe pelo checklist de homologação.
02

Antes de começar

Credenciais

Envie à nossa equipe o nome da sua operação e a URL HTTPS do seu endpoint de callback. Você recebe duas credenciais:

CredencialFormatoUso
ID do operador32 caracteres hexadecimaisVai no cabeçalho X-Operator-ID de todo pedido, nos dois sentidos.
Segredo de assinatura43 caracteres (base64url)Chave do HMAC-SHA256. Use os 43 caracteres como texto, sem decodificar o base64. É mostrado uma única vez, na criação.

Guarde o segredo só no servidor. Ele assina nos dois sentidos: quem o tem consegue abrir sessões em seu nome e forjar respostas da sua carteira. Nunca o envie ao navegador nem o grave em logs. Se houver suspeita de vazamento, avise a nossa equipe na hora.

  • Os jogos são liberados por operador. Consulte o catálogo da API para saber quais estão ativos para você.
  • Para homologar, peça um operador de teste apontado para o seu ambiente de homologação. Ele tem ID e segredo próprios e usa as mesmas URLs desta página.
  • Para trocar a URL de callback, fale com a nossa equipe. A troca só é feita quando não há eventos pendentes.

Valores em dinheiro

Todo valor é um inteiro em unidades de R$ 0,0001, sempre em BRL. Nunca envie decimais nem texto.

ValorEm unidades
R$ 0,101000
R$ 0,404000
R$ 1,0010000
R$ 100,001000000

Identificadores e formatos

ItemFormato
session_id, round_idTexto com um número, como "1042". Trate como identificador opaco: não faça contas com ele nem presuma um tamanho.
game_idTexto ("126"), não número.
transaction_idIdentifica um evento de uma rodada e é a sua chave de idempotência: round:<round_id>:bet, round:<round_id>:prize:<n>, round:<round_id>:reconciliation ou round:<round_id>:refund.
HoráriosX-Timestamp em segundos Unix; expires_at em ISO 8601, UTC.
CorposJSON em UTF-8, com no máximo 64 KB.
03

Assinatura

Todo pedido e toda resposta de callback levam o cabeçalho X-Signature: o HMAC-SHA256 de um texto de poucas linhas, com o seu segredo como chave, em hexadecimal minúsculo. As linhas são unidas por \n, sem \n depois da última.

O texto assinado

Em um pedido são seis linhas. Vale para o catálogo e a abertura de sessão, que você assina, e para os callbacks, que nós assinamos e você confere.

Pedido · 6 linhas
MÉTODO                  POST
CAMINHO                 /backend/v1/operator/sessions
X-Timestamp             1794398400
X-Nonce                 5f2b8c1e9d3a47f6a0b4c7e2d1908f3a
X-Idempotency-Key       (linha vazia na abertura de sessão)
sha256_hex(corpo)       f7adcb29a489fa4d…

Na resposta da sua carteira a um callback são cinco linhas. Sem assinatura válida, o evento não é dado como confirmado.

Resposta · 5 linhas
STATUS HTTP             200
X-Timestamp             o horário da sua resposta
X-Nonce                 o mesmo nonce do pedido
X-Idempotency-Key       a mesma chave do pedido
sha256_hex(corpo)       o hash do corpo da resposta

Cabeçalhos

CabeçalhoConteúdo
X-Operator-IDO seu ID de operador. Vai nos pedidos, nos dois sentidos.
X-TimestampSegundos Unix do envio. A diferença aceita para o relógio de quem recebe é de até 5 minutos.
X-NonceTexto aleatório de 16 a 128 caracteres, novo a cada pedido. Na resposta de um callback, devolva o mesmo nonce que recebeu.
X-Idempotency-KeySó nos callbacks: o transaction_id do evento. O catálogo e a abertura de sessão omitem este cabeçalho e assina uma linha vazia no lugar.
X-SignatureA assinatura, com 64 caracteres hexadecimais minúsculos.

Pedidos com JSON e respostas levam também Content-Type: application/json.

Cuidados

  • O corpo é assinado byte a byte. Calcule o SHA-256 dos bytes que você envia ou recebe, antes de qualquer parser. Um JSON reserializado, com outra ordem de campos ou outros espaços, produz outro hash.
  • O caminho não leva domínio nem query string. Nos callbacks, é o caminho da sua URL cadastrada: para https://carteira.exemplo.com/games/callback, assina-se /games/callback.
  • Relógio sincronizado. Um servidor mais de 5 minutos fora do horário tem todos os pedidos recusados. Use NTP.
  • Um nonce por pedido. O catálogo e a abertura de sessão compartilham o controle de nonces usados.
  • Compare assinaturas em tempo constante (timingSafeEqual, hmac.compare_digest, hash_equals).
04

Testar a assinatura

Confira a sua rotina com estes três casos antes da primeira chamada. Todos usam o segredo de exemplo q7ZkD1mW3xYv9Lr2TnB5cHs8JfU0aEoPgI4wQyK6RtM, o timestamp 1794398400 e o nonce 5f2b8c1e9d3a47f6a0b4c7e2d1908f3a.

Abertura de sessão · pedido assinado por você
Método e caminho
POST /backend/v1/operator/sessions
Chave de idempotência
vazia
Corpo
{"external_session_id":"sessao-8841","player_id":"jogador-123","game_id":"126","balance_units":1000000}
SHA-256 do corpo
f7adcb29a489fa4d6068a40061f61966340e1dfa73e094173518bcddf704f4be
X-Signature
088914e7c6d25304244c42d7c9e3641a389c51ac361c2934e511669d941ec91e
Callback de aposta · pedido assinado por nós
Método e caminho
POST /games/callback
Chave de idempotência
round:1042:bet
Corpo
{"event":"bet","transaction_id":"round:1042:bet","round_id":"1042","session_id":"77","player_id":"jogador-123","game_id":"126","amount_units":4000,"currency":"BRL"}
SHA-256 do corpo
bb0ec7550c7ef7b0efea2240005b94df1239e30eae0c9b09b6ff7bcc25bae02b
X-Signature
8796a5942ca70f912d5fb132ee6bd0d53bd206c61424d56c2bba20a56cf0a2a5
Resposta à aposta · resposta assinada por você
Status HTTP
200
Chave de idempotência
round:1042:bet
Corpo
{"ok":true,"balance_units":996000}
SHA-256 do corpo
54ee745cde48aa2979f2dab7a23051e5c677c16fd0b3f790f94eab2ed0b23c0b
X-Signature
1da5728a2a69e3ea27c69d9fea46f84b9e9def99ee8493dd72eda15ff6e17568

Calculadora

Cole os valores de um pedido seu para ver o texto assinado e a assinatura esperada. O cálculo acontece no seu navegador e esta página não faz nenhuma chamada de rede; ainda assim, prefira um segredo de homologação.

05

Listar jogos

Na configuração local revisada, novas rodadas têm prêmio total limitado a R$ 500.000. Apostas-base máximas: Tiger R$ 200; Ox/Cash R$ 250; Snake/Piñata/Alchemy R$ 100; Mouse/Rabbit/Dragon R$ 500. A Aposta Bônus do Snake custa até R$ 150. Esses limites preservam multiplicadores e RTP; todos os bônus da entrada pertencem ao mesmo teto.

Alchemy Gold (ID 1368367, implementação local ainda sem publicação) usa apostas de R$ 0,50 a R$ 100, abertura R$ 0,50 e teto de 5.000× (até R$ 500 mil), sem compra de recurso. As fases de retenção, pagamento e giros grátis pertencem à mesma entrada financeira.

Piñata Wins (ID 1492288, implementação local ainda sem publicação) usa apostas de R$ 0,20 a R$ 100, abertura R$ 0,20 e nível 1. A compra do recurso custa 75× em toda a faixa (R$ 15 a R$ 7.500); o teto acumulado é 5.000× a aposta-base (até R$ 500 mil). Cascatas e giros grátis pertencem à mesma entrada paga.

Cash Mania (ID 1682240) usa apostas de R$ 0,10 a R$ 250, abertura R$ 0,10 e teto de 2.000×, até R$ 500.000. Giros grátis e reativações pertencem a uma única entrada paga e recebem um prêmio total na carteira.

Fortune Mouse (ID 68) segue o mesmo contrato de sessão e callbacks: apostas de R$ 0,10 a R$ 500, abertura em R$ 1 e prêmio máximo de 1.000×, até R$ 500.000. As repetições são parte de uma única entrada paga. O jogo só aparece no catálogo depois de liberado globalmente e para a sua operação.

Consulte o catálogo pelo seu servidor para montar o lobby. A API devolve os jogos liberados para a sua operação, em ordem de nome. A disponibilidade pode mudar no painel.

GET/backend/v1/operator/gamesresponde 200

Envie X-Operator-ID, X-Timestamp, um X-Nonce novo e X-Signature. Assine o método GET e o caminho acima. A linha de idempotência fica vazia. Envie o pedido sem corpo e sem parâmetros. O SHA-256 do corpo vazio é e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Resposta

O objeto contém um array games. Para cada item, mostre name e use cover_url como src da imagem no lobby. A capa é pública no CDN e pode ser carregada diretamente pelo navegador. Quando o jogador escolher, envie o game_id daquele item à abertura de sessão.

Formato de um item · valores ilustrativos
{
  "games": [{
    "game_id": "123",
    "name": "Jogo de exemplo",
    "provider": "Provedor de exemplo",
    "provider_logo_url": "https://cdn.example/provedor.png",
    "cover_url": "https://cdn.example/capa.jpg",
    "min_bet_units": 1000,
    "max_base_bet_units": 5000000,
    "max_bet_units": 7500000,
    "max_prize_units": 500000000
  }]
}

Use provider para agrupar os jogos no lobby pela marca cadastrada. O campo contém o nome de exibição ou null quando o jogo ainda não tem provedor cadastrado.

Use provider_logo_url para mostrar a logo no filtro ou no cabeçalho do provedor. Ela é uma imagem pública do CDN. Quando esse campo for null, use o nome do provedor, se houver. A capa em cover_url já vem pronta para exibição.

Os valores são inteiros em unidades de R$ 0,0001. min_bet_units é a menor entrada. max_base_bet_units é a maior aposta-base e max_bet_units inclui o custo máximo de opções de aposta. A carteira deve conseguir creditar max_prize_units, o maior prêmio possível em uma rodada do perfil.

Um operador ativo sem jogos liberados recebe 200 com {"games":[]}. Assinatura inválida retorna 401, operador desativado recebe 403 e nonce já utilizado retorna 409. Em uma nova consulta, gere outro nonce.

06

Abrir uma sessão

Chame do seu servidor quando o jogador escolher um item do catálogo. Os exemplos usam o primeiro item disponível. A resposta traz a URL que abre o jogo já autenticado.

POST/backend/v1/operator/sessionsresponde 201

Envie os cabeçalhos de assinatura, sem X-Idempotency-Key.

Pedido

CampoTipoDescrição
external_session_idtexto, 1–128O identificador da sessão no seu sistema. Único por operador.
player_idtexto, 1–128O identificador do jogador no seu sistema. Volta em todos os callbacks.
game_idtextoO ID de um dos jogos liberados para você.
balance_unitsinteiro ≥ 0O saldo atual do jogador, mostrado ao abrir o jogo.

Os quatro campos são obrigatórios. Um campo que não está nesta tabela faz o pedido ser recusado.

Resposta

201 · JSON
{
  "session_id": "77",
  "launch_url": "https://games.bichostars.net/126/index.html#launch=3f9c…64 caracteres hexadecimais",
  "expires_at": "2026-11-12T00:00:00.482913Z"
}
CampoDescrição
session_idO identificador da sessão do nosso lado. É este valor, e não o external_session_id, que vem no campo session_id dos callbacks. Guarde-o junto da sua sessão.
launch_urlA URL que abre o jogo para este jogador. Veja Abrir o jogo.
expires_atQuando a sessão deixa de aceitar pedidos: 12 horas depois desta chamada.

Exemplo

// Node.js 18 ou mais recente, sem dependências.
import { createHash, createHmac, randomBytes } from 'node:crypto';

const BASE_URL = process.env.GAMES_BASE_URL ?? 'https://games.bichostars.net';
const OPERATOR_ID = process.env.GAMES_OPERATOR_ID;
const SECRET = process.env.GAMES_SIGNING_SECRET; // o texto do segredo, sem decodificar

const sha256 = data => createHash('sha256').update(data).digest('hex');
const sign = (...parts) => createHmac('sha256', SECRET).update(parts.join('\n')).digest('hex');

async function operatorRequest(method, path, payload) {
  const body = payload === undefined ? '' : JSON.stringify(payload);
  const timestamp = String(Math.floor(Date.now() / 1000));
  const nonce = randomBytes(16).toString('hex');
  const response = await fetch(BASE_URL + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Operator-ID': OPERATOR_ID,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': sign(method, path, timestamp, nonce, '', sha256(body)),
    },
    body: payload === undefined ? undefined : body,
  });
  if (!response.ok) {
    throw new Error(`Pedido recusado: ${response.status} ${await response.text()}`);
  }
  return response.json();
}

const { games } = await operatorRequest('GET', '/backend/v1/operator/games');
if (!games.length) throw new Error('Nenhum jogo disponível');
const session = await operatorRequest('POST', '/backend/v1/operator/sessions', {
  external_session_id: 'sessao-8841',
  player_id: 'jogador-123',
  game_id: games[0].game_id,
  balance_units: 1_000_000,  // R$ 100,00
});
console.log(session.launch_url);
# Python 3.8 ou mais recente, só com a biblioteca padrão.
import hashlib
import hmac
import json
import os
import secrets
import time
import urllib.request

BASE_URL = os.environ.get("GAMES_BASE_URL", "https://games.bichostars.net")
OPERATOR_ID = os.environ["GAMES_OPERATOR_ID"]
SECRET = os.environ["GAMES_SIGNING_SECRET"].encode()  # o texto do segredo, sem decodificar


def sha256(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def sign(*parts: str) -> str:
    return hmac.new(SECRET, "\n".join(parts).encode(), hashlib.sha256).hexdigest()


def operator_request(method, path, payload=None):
    body = json.dumps(payload).encode() if payload is not None else b""
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    request = urllib.request.Request(BASE_URL + path, data=body if payload is not None else None, method=method, headers={
        "Content-Type": "application/json",
        "X-Operator-ID": OPERATOR_ID,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": sign(method, path, timestamp, nonce, "", sha256(body)),
    })
    # Qualquer status diferente de 2xx levanta urllib.error.HTTPError.
    with urllib.request.urlopen(request, timeout=10) as response:
        return json.load(response)


games = operator_request("GET", "/backend/v1/operator/games")["games"]
if not games:
    raise RuntimeError("Nenhum jogo disponível")
session = operator_request("POST", "/backend/v1/operator/sessions", {
    "external_session_id": "sessao-8841",
    "player_id": "jogador-123",
    "game_id": games[0]["game_id"],
    "balance_units": 1_000_000,
})
print(session["launch_url"])
<?php
// PHP 7.4 ou mais recente, com a extensão curl.
$baseUrl = getenv('GAMES_BASE_URL') ?: 'https://games.bichostars.net';
$operatorId = getenv('GAMES_OPERATOR_ID');
$secret = getenv('GAMES_SIGNING_SECRET'); // o texto do segredo, sem decodificar

function sign(string $secret, string ...$parts): string
{
    return hash_hmac('sha256', implode("\n", $parts), $secret);
}

function operatorRequest(string $baseUrl, string $operatorId, string $secret, string $method, string $path, ?array $payload = null): array
{
    // Assine e envie exatamente os mesmos bytes.
    $body = $payload === null ? '' : json_encode($payload, JSON_THROW_ON_ERROR);
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));
    $request = curl_init($baseUrl . $path);
    curl_setopt_array($request, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-Operator-ID: ' . $operatorId,
            'X-Timestamp: ' . $timestamp,
            'X-Nonce: ' . $nonce,
            'X-Signature: ' . sign($secret, $method, $path, $timestamp, $nonce, '', hash('sha256', $body)),
        ],
    ]);
    if ($payload !== null) curl_setopt($request, CURLOPT_POSTFIELDS, $body);
    $response = curl_exec($request);
    $status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
    curl_close($request);
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException("Pedido recusado: $status $response");
    }
    return json_decode($response, true);
}

$games = operatorRequest($baseUrl, $operatorId, $secret, 'GET', '/backend/v1/operator/games')['games'];
if (!$games) throw new RuntimeException('Nenhum jogo disponível');
$session = operatorRequest($baseUrl, $operatorId, $secret, 'POST', '/backend/v1/operator/sessions', [
    'external_session_id' => 'sessao-8841',
    'player_id' => 'jogador-123',
    'game_id' => $games[0]['game_id'],
    'balance_units' => 1000000,   // R$ 100,00
]);
echo $session['launch_url'], "\n";

Repetir a abertura

  • Chamar de novo com o mesmo external_session_id devolve a mesma sessão com um token novo e renova a validade por 12 horas. O token anterior continua valendo até expirar, então um jogador que já está no jogo não é derrubado.
  • Na repetição, o jogador e o jogo precisam ser os mesmos; caso contrário a resposta é 409. O balance_units da repetição é ignorado: o saldo da sessão continua sendo o da abertura ou o da sua última resposta de carteira.
  • Cada chamada, repetida ou não, leva timestamp e nonce novos.

Erros

O corpo do erro é sempre {"error":"…"}.

StatuserrorCausa
400invalid JSONJSON malformado, campo desconhecido, tipo errado (por exemplo game_id numérico) ou corpo acima de 64 KB.
401invalid signatureCabeçalho ausente, operador desconhecido, timestamp fora dos 5 minutos, nonce fora de 16–128 caracteres ou assinatura que não confere.
402ggr credit exhaustedSua operação é pré-paga e o crédito de GGR da categoria do jogo acabou. Compre crédito e abra a sessão de novo.
403game disabledO jogo não está liberado para o seu operador, ou o operador está desativado.
409conflictCampo vazio ou longo demais, saldo negativo, game_id que não existe, nonce já usado, ou external_session_id já aberto para outro jogador ou outro jogo.
500internal errorFalha do nosso lado. Repita com timestamp e nonce novos.
07

Abrir o jogo

Leve o navegador do jogador para a launch_url, por redirecionamento, nova aba ou webview. O jogo lê o token, tira-o da barra de endereço e passa a falar com a nossa API por conta própria.

A launch_url é uma credencial. Quem a tem joga com o saldo do jogador até a sessão expirar. Entregue-a só ao jogador da sessão e não a grave em logs, ferramentas de analytics ou mensagens. O token vai no fragmento (#launch=) para não aparecer em logs de acesso de servidores.

SessãoUma sessão é de um jogador em um jogo. Para outro jogo, abra outra sessão.
Validade12 horas. Para continuar depois disso, repita a abertura com o mesmo external_session_id ou abra uma sessão nova.
Saldo na telaO da abertura e, a partir da primeira rodada, o balance_units das suas respostas a bet, prize e refund. Um depósito feito fora do jogo aparece na rodada seguinte.
HistóricoO histórico dentro do jogo mostra as rodadas daquela sessão.
Página inteiraO jogo foi verificado aberto como página de nível superior. O uso dentro de iframe não foi homologado.
08

Callbacks de carteira

Cada evento de uma rodada chega à sua URL de callback como um POST. Para cada um, você faz três coisas: confere a assinatura, registra o evento na carteira e responde com o saldo, também assinado.

POSThttps://sua-carteira/…a URL que você cadastrou

Os quatro eventos

EventoQuando chegaO que fazer
betUma vez, quando a rodada abre.Debite amount_units do saldo do jogador, ou recuse a aposta.
prizeSó quando a rodada paga.Credite amount_units. Não pode ser recusado.
reconciliationSempre, por último. Fecha a rodada.Não mexa no saldo. Marque a rodada como encerrada e confira os totais.
refundSó quando cancelamos uma rodada cuja aposta nunca foi confirmada.Devolva a aposta, se você a debitou. Veja Cancelamento e refund.

A ordem dos eventos

RodadaEventos, nesta ordem
Sem prêmiobet → reconciliation
Com prêmiobet → prize → reconciliation
Aposta recusada por vocêbet, respondido com 409. Nenhum outro evento.
Cancelada por nósbet sem confirmação → refund → reconciliation
  • A reconciliation é o sinal de que a rodada acabou. Não conte prêmios para decidir isso: hoje há no máximo um prize por rodada, mas o contrato permite vários.
  • Rodadas grátis, respins e bônus fazem parte da mesma rodada: uma aposta só, e o prêmio de tudo em prize.
  • O jogador vê o resultado quando bet e prize estão confirmados. A reconciliation vem logo em seguida e não segura a tela dele.
  • Cada sessão tem uma rodada por vez. A aposta seguinte só é enviada depois que você confirma a reconciliation da anterior, então os eventos de uma sessão chegam sempre em ordem. Sessões diferentes chegam em paralelo.

O pedido que você recebe

Vem com os cabeçalhos de assinatura. O X-Idempotency-Key é igual ao transaction_id do corpo, o X-Nonce tem 32 caracteres hexadecimais e a assinatura usa o caminho da sua URL de callback.

bet · aposta de R$ 0,40
{
  "event": "bet",
  "transaction_id": "round:1042:bet",
  "round_id": "1042",
  "session_id": "77",
  "player_id": "jogador-123",
  "game_id": "126",
  "amount_units": 4000,
  "currency": "BRL"
}

prize e refund têm os mesmos campos, com transaction_id round:1042:prize:1 e round:1042:refund. A reconciliation leva também os totais da rodada:

reconciliation · rodada que pagou R$ 0,80
{
  "event": "reconciliation",
  "transaction_id": "round:1042:reconciliation",
  "round_id": "1042",
  "session_id": "77",
  "player_id": "jogador-123",
  "game_id": "126",
  "amount_units": 0,
  "currency": "BRL",
  "total_bet_units": 4000,
  "total_prize_units": 8000,
  "total_refund_units": 0,
  "ggr_units": -4000
}

O corpo real vem em uma linha só, sem espaços; as quebras acima são só para leitura.

CampoTipoDescrição
eventtextobet, prize, reconciliation ou refund.
transaction_idtextoIdentificador único do evento. Repetições do mesmo evento trazem o mesmo valor. Os prêmios são numerados a partir de 1.
round_idtextoA rodada. Todos os eventos de uma rodada têm o mesmo round_id.
session_idtextoO session_id que a abertura de sessão devolveu.
player_idtextoO player_id que você informou na abertura.
game_idtextoO jogo da sessão.
amount_unitsinteiro ≥ 0O valor que o evento movimenta: a aposta em bet, o prêmio em prize, a aposta a devolver em refund. Sempre 0 na reconciliation.
currencytextoSempre BRL.
total_bet_unitsinteiro ≥ 0Só na reconciliation: o valor da aposta da rodada. Em rodada cancelada, o mesmo valor de total_refund_units.
total_prize_unitsinteiro ≥ 0Só na reconciliation: a soma dos prêmios da rodada. Zero quando ela não pagou.
total_refund_unitsinteiro ≥ 0Só na reconciliation: o valor devolvido em uma rodada cancelada. Zero nas outras.
ggr_unitsinteiroSó na reconciliation: total_bet_units − total_prize_units − total_refund_units. Negativo quando o jogador ganhou mais do que apostou.

Ignore campos que você não conhece: podemos acrescentar campos a estes corpos sem mudar a versão da API.

A resposta que você devolve

Responda com JSON e com os cabeçalhos X-Timestamp, X-Nonce (o mesmo do pedido) e X-Signature (a assinatura de resposta).

SituaçãoStatusCorpoEfeito
Evento registrado200{"ok":true,"balance_units":996000}Confirmado. balance_units é o saldo do jogador depois do evento.
Aposta recusada409{"ok":false,"code":"INSUFFICIENT_FUNDS"}A rodada termina sem cobrança e nenhum outro evento dela é enviado. Só vale para bet.
Qualquer outra resposta——Não confirmado: o mesmo evento é enviado de novo. Veja Repetições e falhas.
  • balance_units é obrigatório em todo 200, como inteiro igual ou maior que zero. Na reconciliation, envie o saldo atual. Um saldo ausente ou nulo deixa o evento pendente.
  • O 409 assinado é a única forma de recusar uma aposta. Use-o também para jogador bloqueado ou limite atingido. Outro 4xx ou 5xx não cancela nada: a aposta continua sendo reenviada.
  • A resposta ao refund leva um campo a mais, o recibo refunded_units. Veja Cancelamento e refund.

Exemplo

Um endpoint completo: confere a assinatura sobre os bytes recebidos, reconhece eventos repetidos pelo transaction_id, trata os quatro eventos e responde assinado. A carteira do exemplo é de demonstração e dá R$ 100,00 a cada jogador novo.

// Node.js 18 ou mais recente, sem dependências.
import { createServer } from 'node:http';
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

const OPERATOR_ID = process.env.GAMES_OPERATOR_ID;
const SECRET = process.env.GAMES_SIGNING_SECRET;
const CALLBACK_PATH = '/games/callback'; // o caminho da URL de callback cadastrada

const sha256 = data => createHash('sha256').update(data).digest('hex');
const sign = (...parts) => createHmac('sha256', SECRET).update(parts.join('\n')).digest('hex');
const sameText = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));

// Carteira de demonstração em memória. Na sua carteira, grave o lançamento com
// transaction_id único e atualize o saldo na mesma transação do banco.
const balances = new Map();
const ledger = new Map(); // transaction_id -> resposta já dada

function applyTransaction(message) {
  const known = ledger.get(message.transaction_id);
  if (known) return known; // repetição: devolve a mesma resposta, sem lançar de novo
  const balance = balances.get(message.player_id) ?? 1_000_000;
  let next = balance;
  let refused = false;
  let refunded = 0;
  if (message.event === 'bet') {
    // Sem saldo, ou aposta de uma rodada que já foi estornada: não debita.
    refused = balance < message.amount_units || ledger.has(`round:${message.round_id}:refund`);
    if (!refused) next = balance - message.amount_units;
  } else if (message.event === 'prize') {
    next = balance + message.amount_units;
  } else if (message.event === 'refund') {
    // Devolve só a aposta que foi debitada, e o recibo diz quanto devolveu:
    // o valor da aposta, ou zero se ela nunca chegou.
    refunded = ledger.get(`round:${message.round_id}:bet`)?.status === 200 ? message.amount_units : 0;
    next = balance + refunded;
  }
  // reconciliation fecha a rodada e não movimenta saldo. É o lugar de conferir
  // total_bet_units, total_prize_units e total_refund_units com os seus lançamentos.
  balances.set(message.player_id, next);
  const result = refused
    ? { status: 409, body: { ok: false, code: 'INSUFFICIENT_FUNDS' } }
    : { status: 200, body: { ok: true, balance_units: next, ...(message.event === 'refund' && { refunded_units: refunded }) } };
  ledger.set(message.transaction_id, result);
  return result;
}

createServer(async (request, response) => {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  const raw = Buffer.concat(chunks); // os bytes recebidos, antes de qualquer parser

  const timestamp = request.headers['x-timestamp'] ?? '';
  const nonce = request.headers['x-nonce'] ?? '';
  const key = request.headers['x-idempotency-key'] ?? '';
  const expected = sign('POST', CALLBACK_PATH, timestamp, nonce, key, sha256(raw));
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  if (request.method !== 'POST' || request.url !== CALLBACK_PATH
      || request.headers['x-operator-id'] !== OPERATOR_ID || !fresh
      || !sameText(expected, request.headers['x-signature'] ?? '')) {
    response.writeHead(401).end();
    return;
  }

  const message = JSON.parse(raw);
  if (message.transaction_id !== key || !['bet', 'prize', 'reconciliation', 'refund'].includes(message.event)) {
    response.writeHead(400).end();
    return;
  }
  const { status, body } = applyTransaction(message);

  // A resposta também é assinada, com o mesmo nonce do pedido.
  const text = JSON.stringify(body);
  const now = String(Math.floor(Date.now() / 1000));
  response.writeHead(status, {
    'Content-Type': 'application/json',
    'X-Timestamp': now,
    'X-Nonce': nonce,
    'X-Signature': sign(String(status), now, nonce, key, sha256(text)),
  }).end(text);
}).listen(3000);
# Python 3.8 ou mais recente, só com a biblioteca padrão.
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Lock

OPERATOR_ID = os.environ["GAMES_OPERATOR_ID"]
SECRET = os.environ["GAMES_SIGNING_SECRET"].encode()
CALLBACK_PATH = "/games/callback"  # o caminho da URL de callback cadastrada

# Carteira de demonstração em memória. Na sua carteira, grave o lançamento com
# transaction_id único e atualize o saldo na mesma transação do banco.
balances = {}
ledger = {}  # transaction_id -> resposta já dada
lock = Lock()


def sha256(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def sign(*parts: str) -> str:
    return hmac.new(SECRET, "\n".join(parts).encode(), hashlib.sha256).hexdigest()


def apply_transaction(message):
    with lock:
        known = ledger.get(message["transaction_id"])
        if known:
            return known  # repetição: devolve a mesma resposta, sem lançar de novo
        balance = balances.get(message["player_id"], 1_000_000)
        amount, event, round_id = message["amount_units"], message["event"], message["round_id"]
        refused = False
        if event == "bet":
            # Sem saldo, ou aposta de uma rodada que já foi estornada: não debita.
            refused = balance < amount or f"round:{round_id}:refund" in ledger
            if not refused:
                balance -= amount
        elif event == "prize":
            balance += amount
        elif event == "refund":
            # Devolve só a aposta que foi debitada, e o recibo diz quanto devolveu:
            # o valor da aposta, ou zero se ela nunca chegou.
            refunded = amount if ledger.get(f"round:{round_id}:bet", (0, None))[0] == 200 else 0
            balance += refunded
        # reconciliation fecha a rodada e não movimenta saldo. É o lugar de conferir
        # total_bet_units, total_prize_units e total_refund_units com os seus lançamentos.
        balances[message["player_id"]] = balance
        if refused:
            result = (409, {"ok": False, "code": "INSUFFICIENT_FUNDS"})
        else:
            result = (200, {"ok": True, "balance_units": balance})
            if event == "refund":
                result[1]["refunded_units"] = refunded
        ledger[message["transaction_id"]] = result
        return result


class Callback(BaseHTTPRequestHandler):
    def do_POST(self):
        # Os bytes recebidos, antes de qualquer parser.
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        timestamp = self.headers.get("X-Timestamp", "")
        nonce = self.headers.get("X-Nonce", "")
        key = self.headers.get("X-Idempotency-Key", "")
        expected = sign("POST", CALLBACK_PATH, timestamp, nonce, key, sha256(raw))
        fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) <= 300
        if (self.path != CALLBACK_PATH or self.headers.get("X-Operator-ID") != OPERATOR_ID
                or not fresh or not hmac.compare_digest(expected, self.headers.get("X-Signature", ""))):
            self.send_response(401)
            self.end_headers()
            return

        message = json.loads(raw)
        if message.get("transaction_id") != key or message.get("event") not in ("bet", "prize", "reconciliation", "refund"):
            self.send_response(400)
            self.end_headers()
            return
        status, payload = apply_transaction(message)

        # A resposta também é assinada, com o mesmo nonce do pedido.
        body = json.dumps(payload).encode()
        now = str(int(time.time()))
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.send_header("X-Timestamp", now)
        self.send_header("X-Nonce", nonce)
        self.send_header("X-Signature", sign(str(status), now, nonce, key, sha256(body)))
        self.end_headers()
        self.wfile.write(body)


ThreadingHTTPServer(("0.0.0.0", 3000), Callback).serve_forever()
<?php
// PHP 7.4 ou mais recente, com pdo_sqlite. Sirva este arquivo na URL de callback.
$operatorId = getenv('GAMES_OPERATOR_ID');
$secret = getenv('GAMES_SIGNING_SECRET');
$callbackPath = '/games/callback'; // o caminho da URL de callback cadastrada

function sign(string $secret, string ...$parts): string
{
    return hash_hmac('sha256', implode("\n", $parts), $secret);
}

$raw = file_get_contents('php://input'); // os bytes recebidos, antes de qualquer parser
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$nonce = $_SERVER['HTTP_X_NONCE'] ?? '';
$key = $_SERVER['HTTP_X_IDEMPOTENCY_KEY'] ?? '';
$expected = sign($secret, 'POST', $callbackPath, $timestamp, $nonce, $key, hash('sha256', $raw));
if ($_SERVER['REQUEST_METHOD'] !== 'POST'
    || parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) !== $callbackPath
    || ($_SERVER['HTTP_X_OPERATOR_ID'] ?? '') !== $operatorId
    || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300
    || !hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

$message = json_decode($raw, true);
if (($message['transaction_id'] ?? null) !== $key
    || !in_array($message['event'] ?? '', ['bet', 'prize', 'reconciliation', 'refund'], true)) {
    http_response_code(400);
    exit;
}

// Carteira de demonstração em SQLite. Na sua carteira, o lançamento com
// transaction_id único e o saldo mudam na mesma transação do banco.
$db = new PDO('sqlite:' . sys_get_temp_dir() . '/carteira-demo.sqlite');
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->exec('CREATE TABLE IF NOT EXISTS balances(player_id TEXT PRIMARY KEY, units INTEGER NOT NULL)');
$db->exec('CREATE TABLE IF NOT EXISTS ledger(transaction_id TEXT PRIMARY KEY, status INTEGER NOT NULL, body TEXT NOT NULL)');
$db->exec('BEGIN IMMEDIATE');
$known = $db->prepare('SELECT status, body FROM ledger WHERE transaction_id = ?');
$known->execute([$key]);
$row = $known->fetch(PDO::FETCH_ASSOC);
if ($row) {
    // Repetição: devolve a mesma resposta, sem lançar de novo.
    $status = (int) $row['status'];
    $body = $row['body'];
} else {
    $stored = $db->prepare('SELECT units FROM balances WHERE player_id = ?');
    $stored->execute([$message['player_id']]);
    $units = $stored->fetchColumn();
    $balance = $units === false ? 1000000 : (int) $units;
    $amount = (int) $message['amount_units'];
    $answered = $db->prepare('SELECT status FROM ledger WHERE transaction_id = ?');
    $round = 'round:' . $message['round_id'];
    $refused = false;
    if ($message['event'] === 'bet') {
        // Sem saldo, ou aposta de uma rodada que já foi estornada: não debita.
        $answered->execute([$round . ':refund']);
        $refused = $balance < $amount || $answered->fetchColumn() !== false;
        if (!$refused) {
            $balance -= $amount;
        }
    } elseif ($message['event'] === 'prize') {
        $balance += $amount;
    } elseif ($message['event'] === 'refund') {
        // Devolve só a aposta que foi debitada, e o recibo diz quanto devolveu:
        // o valor da aposta, ou zero se ela nunca chegou.
        $answered->execute([$round . ':bet']);
        $refunded = (int) $answered->fetchColumn() === 200 ? $amount : 0;
        $balance += $refunded;
    }
    // reconciliation fecha a rodada e não movimenta saldo. É o lugar de conferir
    // total_bet_units, total_prize_units e total_refund_units com os seus lançamentos.
    $db->prepare('REPLACE INTO balances(player_id, units) VALUES(?, ?)')
        ->execute([$message['player_id'], $balance]);
    $status = $refused ? 409 : 200;
    $answer = ['ok' => true, 'balance_units' => $balance];
    if ($message['event'] === 'refund') {
        $answer['refunded_units'] = $refunded;
    }
    $body = json_encode($refused ? ['ok' => false, 'code' => 'INSUFFICIENT_FUNDS'] : $answer);
    $db->prepare('INSERT INTO ledger(transaction_id, status, body) VALUES(?, ?, ?)')
        ->execute([$key, $status, $body]);
}
$db->exec('COMMIT');

// A resposta também é assinada, com o mesmo nonce do pedido.
$now = (string) time();
http_response_code($status);
header('Content-Type: application/json');
header('X-Timestamp: ' . $now);
header('X-Nonce: ' . $nonce);
header('X-Signature: ' . sign($secret, (string) $status, $now, $nonce, $key, hash('sha256', $body)));
echo $body;

Requisitos do endpoint

  • Responda em até 8 segundos. Depois disso a chamada é abandonada e repetida. O jogador espera as respostas de bet e prize com os rolos girando, então mire em bem menos de um segundo.
  • HTTPS com certificado válido e sem redirecionamento: uma resposta 3xx não é seguida.
  • Resposta de até 64 KB.
  • IP de origem fixo. As nossas chamadas saem sempre de 54.232.137.142. Se você filtra por IP, libere esse endereço; avisamos com antecedência antes de qualquer mudança ou acréscimo. A autenticação continua sendo a assinatura.
09

Repetições e falhas

Um evento sem confirmação nunca é descartado: ele é reenviado com o mesmo transaction_id até a sua carteira confirmar. Por isso o mesmo evento pode chegar mais de uma vez, por exemplo quando a sua resposta se perde depois de você já ter lançado.

Idempotência

  • Grave cada transaction_id com restrição de unicidade, na mesma transação de banco que altera o saldo.
  • Ao receber um transaction_id que já existe, não lance de novo e devolva a mesma resposta da primeira vez, com o mesmo saldo.

O que conta como não confirmado

  • Tempo esgotado (8 segundos), falha de conexão ou de TLS.
  • Status diferente de 200, fora o 409 de recusa em uma bet.
  • Resposta sem X-Signature válida, com X-Nonce diferente do pedido ou com X-Timestamp mais de 5 minutos fora.
  • Corpo que não é o JSON esperado, ok falso em um 200, ou balance_units ausente, nulo ou negativo.
  • Em um refund, resposta sem refunded_units ou com valor diferente de zero e da aposta.

Quando reenviamos

QuandoO que fazemos
Primeira falhaNova tentativa em 1 segundo. A cada falha a espera dobra, até 256 segundos.
Carteira sem responderAs chamadas ao seu endpoint são espaçadas, com pausa de 2 segundos até 1 minuto entre sondagens. A primeira resposta válida encerra a pausa e as pendências são enviadas em ordem.
Quinta falha do mesmo eventoA rodada é marcada para atenção e a nossa equipe é alertada. As tentativas continuam.
24 horas sem confirmaçãoAs tentativas automáticas param. O evento continua registrado e só volta a ser enviado depois de conferido com você.

Prêmios e reconciliações pendentes nunca são cancelados, só reenviados. Uma aposta que ficou sem confirmação pode ser cancelada pela nossa equipe: veja Cancelamento e refund.

O que o jogador vê

  • Enquanto bet ou prize estão pendentes, o resultado não é mostrado. O jogo espera pelo menos 30 segundos e então avisa que não foi possível concluir.
  • Uma reconciliation pendente não esconde o resultado da rodada, que já foi paga, mas segura a aposta seguinte da sessão até ser confirmada.

Depois de uma indisponibilidade sua, não é preciso fazer nada: os eventos pendentes chegam sozinhos, com os mesmos transaction_id. Com a idempotência implementada, nenhum é lançado em dobro. Para conferir uma rodada com a nossa equipe, informe o round_id.

10

Cancelamento e refund

O refund existe para um único caso: uma aposta que enviamos e cuja confirmação nunca recebemos, por exemplo porque a sua carteira ficou fora do ar. Depois de conferir a situação com você, a nossa equipe pode cancelar essa rodada. O resultado dela nunca foi mostrado ao jogador.

Uma rodada com aposta confirmada nunca é cancelada. Ela segue até o prêmio e o fechamento, ainda que com atraso.

Como responder

Nós não sabemos se a aposta chegou a ser debitada; a sua carteira sabe. A resposta ao refund diz o que aconteceu, no campo refunded_units:

Situação na sua carteiraO que fazerrefunded_units
Você debitou a aposta daquela rodadaCredite amount_units de volta e responda 200 com o novo saldo.O valor da aposta
A aposta nunca chegou, ou você a recusouNão credite nada e responda 200 com o saldo atual.0
Resposta a um refund de R$ 0,40 que tinha sido debitado
{ "ok": true, "balance_units": 1000000, "refunded_units": 4000 }
  • refunded_units é obrigatório. Só são aceitos o valor inteiro da aposta ou zero. Sem o campo, ou com outro valor, a resposta não vale como confirmação e o refund é reenviado.
  • Guarde o refund. Se a bet daquela rodada chegar depois dele, por um pedido atrasado na rede, não debite: responda com o 409 de recusa.

O que vem depois

A reconciliation da rodada cancelada repete o que a sua resposta informou. ggr_units é zero nos dois casos.

Sua resposta ao refundtotal_bet_unitstotal_refund_units
refunded_units igual à apostaA apostaA aposta
refunded_units igual a 000
11

Crédito de GGR

Vale só para operações pré-pagas. Se a sua não é, nada desta seção se aplica: prepaid vem false e você nunca é bloqueado. Na operação pré-paga você compra crédito por PIX antes de os jogadores apostarem, e o crédito é gasto pelo GGR das rodadas.

Como o crédito funciona

  • GGR de uma rodada é a aposta menos o prêmio. É o mesmo ggr_units que você recebe no callback reconciliation.
  • O crédito é contado em GGR, por categoria de jogo: slots e live (mesas ao vivo). Cada categoria tem a sua taxa e o seu crédito.
  • Cada rodada fechada desconta o GGR dela. Rodada que o jogador ganhou tem GGR negativo e devolve crédito.
  • Quando o crédito acaba, novas sessões respondem 402 e novas apostas são recusadas. As rodadas já abertas terminam e pagam normalmente.

Conversão: quanto crédito um pagamento compra

Você paga a taxa sobre o GGR adiantada. O crédito é o pagamento dividido pela taxa da categoria:

Fórmula
crédito = pagamento ÷ taxa

credit_units = amount_units × 10000 ÷ ggr_rate_bps   (arredondado para baixo ao centavo)
TaxaVocê pagaCrédito de GGR
5%R$ 5.000,00R$ 100.000,00
5%R$ 100,00R$ 2.000,00
8%R$ 5.000,00R$ 62.500,00
12,5%R$ 1.000,00R$ 8.000,00

Exemplo completo: com taxa de 5% você paga R$ 5.000,00 e recebe R$ 100.000,00 de crédito. Se os seus jogadores apostarem R$ 1.000.000,00 e ganharem R$ 970.000,00, o GGR é R$ 30.000,00 e o crédito cai para R$ 70.000,00.

A taxa de cada compra é a do momento em que o PIX é gerado. Uma mudança de taxa depois não altera crédito já comprado.

Consultar taxas e crédito

GET/backend/v1/operator/billingresponde 200

Assine como o catálogo: método GET, o caminho acima, sem corpo e sem parâmetros, com nonce novo.

Resposta · operação pré-paga a 5% com R$ 100.000,00 de crédito
{
  "prepaid": true,
  "currency": "BRL",
  "categories": [
    {
      "category": "slots",
      "ggr_rate_bps": 500,
      "ggr_rate_percent": "5.00",
      "credit_units": 1000000000,
      "negative_limit_units": 0,
      "blocked": false,
      "credit_per_real_units": 200000
    },
    {
      "category": "live",
      "ggr_rate_bps": null,
      "ggr_rate_percent": null,
      "credit_units": 0,
      "negative_limit_units": 0,
      "blocked": false,
      "credit_per_real_units": null
    }
  ],
  "purchases_available": true,
  "min_amount_units": 10000,
  "max_amount_units": 10000000000
}
CampoSignificado
prepaidSe a sua operação é pré-paga. Com false, ignore o resto.
ggr_rate_bpsA taxa em centésimos de por cento: 500 é 5%. null significa que a categoria não é vendida nem cobrada.
ggr_rate_percentA mesma taxa em texto, para exibir.
credit_unitsO crédito de GGR que resta, em unidades de R$ 0,0001. Pode ficar negativo até o limite.
negative_limit_unitsAté quanto o crédito pode ficar negativo antes do bloqueio. É definido pela nossa equipe.
blockedtrue quando credit_units + negative_limit_units é zero ou menos: os jogos da categoria não aceitam aposta nova.
credit_per_real_unitsQuanto crédito R$ 1,00 compra na taxa atual. A 5%, 200000 (R$ 20,00).
purchases_availableSe você consegue gerar um PIX agora.
min_amount_units, max_amount_unitsO menor e o maior pagamento aceitos em uma compra nova. O mínimo pode ser definido por nós em dólar (USDT) e convertido em reais todo dia à meia-noite de Brasília; por isso leia min_amount_units do dia antes de oferecer valores e não o guarde de um dia para o outro. Sem mínimo definido, é R$ 1,00 (10000).

Comprar crédito por PIX

POST/backend/v1/operator/billing/purchasesresponde 201

Envie os cabeçalhos de assinatura, sem X-Idempotency-Key, como na abertura de sessão.

CampoTipoDescrição
purchase_idtextoO seu identificador da compra: 8 a 64 caracteres entre letras, números, - e _. Repetir o mesmo valor devolve a mesma compra, sem gerar outro PIX.
categorytextoslots ou live. A categoria precisa ter taxa.
amount_unitsinteiroQuanto você vai pagar, em unidades de R$ 0,0001, em centavos inteiros. R$ 5.000,00 é 50000000. Entre o min_amount_units do dia e o max_amount_units de GET /backend/v1/operator/billing; repetir uma compra já feita com o mesmo purchase_id continua valendo mesmo que o mínimo tenha mudado depois.
Pedido
{"purchase_id":"compra-2026-11-0001","category":"slots","amount_units":50000000}
Resposta 201 · valores ilustrativos
{
  "purchase_id": "compra-2026-11-0001",
  "id": "41",
  "status": "pending",
  "category": "slots",
  "amount_units": 50000000,
  "ggr_rate_bps": 500,
  "credit_units": 1000000000,
  "pix_copy_paste": "00020101021226930014br.gov.bcb.pix...",
  "qr_code_png_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2026-11-14T15:30:00Z",
  "created_at": "2026-11-14T15:00:00Z",
  "paid_at": null
}
  • credit_units já é o crédito que este pagamento vai gerar. Mostre ao usuário antes de ele pagar.
  • Pague com pix_copy_paste (PIX copia e cola) ou exiba qr_code_png_base64, uma imagem PNG em base64.
  • O PIX vale até expires_at, 30 minutos depois de gerado, e precisa ser pago no valor exato.
  • O crédito entra sozinho quando o banco confirma o pagamento, em geral em poucos segundos.
  • Você pode ter até 20 compras aguardando pagamento ao mesmo tempo.

Acompanhar uma compra

GET/backend/v1/operator/billing/purchases/{purchase_id}responde 200

Assine o método GET e o caminho com o seu purchase_id, sem corpo. A resposta tem o mesmo formato da compra. Consulte a cada 10 a 30 segundos enquanto status for pending; depois de paid, leia o crédito novo em Consultar taxas e crédito.

statusSignificado
creatingO PIX ainda está sendo gerado. Consulte de novo em instantes.
pendingAguardando o pagamento. Só neste estado a resposta traz o código e a imagem do PIX.
paidPago e creditado. paid_at tem a hora.
expiredNão foi pago a tempo. Faça outra compra, com outro purchase_id.
failedO PIX não pôde ser gerado. Faça outra compra, com outro purchase_id.
reversedO pagamento foi devolvido pelo banco e o crédito dele foi retirado.

GET /backend/v1/operator/billing/purchases, assinado do mesmo jeito, devolve {"purchases":[…]} com as suas 50 compras mais recentes, sem o código do PIX.

Erros

StatuserrorCausa
401invalid signatureAssinatura, timestamp ou nonce inválidos.
403game disabledO operador está desativado.
404not foundNão existe compra sua com esse purchase_id.
409conflictNonce já usado, purchase_id fora do formato, categoria desconhecida, valor fora dos limites ou com fração de centavo, ou purchase_id repetido com outro valor ou outra categoria.
409prepaid billing is not availableA sua operação não é pré-paga, a categoria não tem taxa ou a compra por PIX ainda não foi habilitada para você.
429too many open purchasesJá há 20 compras suas aguardando pagamento.

Acompanhe o crédito antes de ele acabar. Consulte credit_units periodicamente e compre com folga: quando a categoria fica blocked, o jogador que está no meio da sessão vê o jogo como indisponível na aposta seguinte.

14

Checklist de homologação

Antes de liberar para jogadores reais, confirme cada item no seu ambiente de homologação. As marcações ficam salvas só neste navegador.

Assinatura

Sessão e jogo

Rodadas

Repetições, falhas e refund

15

Problemas comuns

A abertura de sessão responde 401 invalid signature
  • O corpo enviado não é byte a byte o corpo assinado. Monte o JSON uma vez, assine esse texto e envie esse mesmo texto.
  • O segredo foi decodificado de base64. Use os 43 caracteres como texto.
  • A linha da chave de idempotência não ficou vazia: na abertura de sessão o texto assinado tem dois \n seguidos entre o nonce e o hash.
  • O caminho assinado inclui o domínio ou difere de /backend/v1/operator/sessions.
  • O relógio do servidor está mais de 5 minutos fora, ou o timestamp foi enviado em milissegundos.
  • O nonce tem menos de 16 caracteres.

Reproduza o pedido na calculadora para ver qual linha difere.

A abertura de sessão responde 409 conflict
  • O nonce já foi usado em uma abertura de sessão ou consulta ao catálogo.
  • O external_session_id já pertence a uma sessão de outro jogador ou de outro jogo.
  • O game_id não é um dos IDs do catálogo da API, ou algum campo está vazio.
O jogo abre e não sai da tela de carregamento
  • A URL foi aberta sem o fragmento #launch=…. Alguns redirecionadores e encurtadores removem o fragmento.
  • A sessão expirou. Repita a abertura para obter uma URL nova.
O jogo fica girando e termina em erro

A sua carteira recebeu a bet ou o prize, mas a resposta não foi aceita como confirmação. As causas mais comuns:

  • Resposta sem X-Signature, ou assinada sobre um corpo diferente do que foi enviado (por exemplo, um framework que reformata o JSON depois da assinatura).
  • X-Nonce da resposta diferente do nonce do pedido.
  • Status 201, 204 ou outro 2xx no lugar de 200.
  • Assinatura de resposta calculada com o formato de pedido. A resposta tem cinco linhas e começa pelo status HTTP.
  • Resposta sem balance_units.
  • Resposta depois de 8 segundos, ou um redirecionamento na frente do endpoint.
A rodada pagou, mas a aposta seguinte não abre

A reconciliation da rodada anterior não foi confirmada. Ela não movimenta saldo, mas é obrigatória: precisa da mesma resposta 200 assinada, com ok verdadeiro e balance_units. Um endpoint que ignora o evento, devolve 204 ou responde sem assinatura deixa a sessão esperando.

O jogador foi debitado ou creditado duas vezes

O mesmo transaction_id foi lançado mais de uma vez. Toda repetição de um evento traz o mesmo transaction_id; a carteira precisa reconhecê-lo e devolver a resposta original sem alterar o saldo. Veja Idempotência.

Como saber que uma rodada terminou

Pela reconciliation. Ela é sempre o último evento da rodada e traz os totais. Não use a chegada de um prize como fim: uma rodada pode não ter prêmio, e um jogo pode ter mais de um.