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
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.
Abertura de sessão
POST /backend/v1/operator/sessions
Uma vez por jogador e jogo. Devolve a URL que abre o jogo.
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
- Seu servidor→API
Abre a sessão com o jogador, o jogo e o saldo atual. Recebe a
launch_url. - Seu servidor→Jogador
Abre a
launch_urlno navegador do jogador. Daqui em diante o jogo fala direto com a nossa API. - API→Sua carteira
O jogador gira e você recebe
bet. Debita a aposta e responde com o novo saldo. - API→Sua carteira
Se a rodada pagou, você recebe
prize. Credita o prêmio e responde com o novo saldo. - API→Jogador
O resultado aparece na tela, com o saldo que a sua carteira informou.
- API→Sua carteira
Você recebe
reconciliation, que fecha a rodada com os totais. Toda rodada termina com ela.
O que implementar, nesta ordem
- Peça as credenciais à nossa equipe.
- Escreva a rotina de assinatura e confira com os vetores de teste.
- Consulte o catálogo para exibir os jogos e suas capas.
- Abra uma sessão e leve o jogador para o jogo.
- Publique o endpoint de callback.
- Trate as repetições e o refund.
- Passe pelo checklist de homologação.
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:
| Credencial | Formato | Uso |
|---|---|---|
| ID do operador | 32 caracteres hexadecimais | Vai no cabeçalho X-Operator-ID de todo pedido, nos dois sentidos. |
| Segredo de assinatura | 43 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.
| Valor | Em unidades |
|---|---|
| R$ 0,10 | 1000 |
| R$ 0,40 | 4000 |
| R$ 1,00 | 10000 |
| R$ 100,00 | 1000000 |
Identificadores e formatos
| Item | Formato |
|---|---|
session_id, round_id | Texto com um número, como "1042". Trate como identificador opaco: não faça contas com ele nem presuma um tamanho. |
game_id | Texto ("126"), não número. |
transaction_id | Identifica 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ários | X-Timestamp em segundos Unix; expires_at em ISO 8601, UTC. |
| Corpos | JSON em UTF-8, com no máximo 64 KB. |
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.
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.
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 respostaCabeçalhos
| Cabeçalho | Conteúdo |
|---|---|
X-Operator-ID | O seu ID de operador. Vai nos pedidos, nos dois sentidos. |
X-Timestamp | Segundos Unix do envio. A diferença aceita para o relógio de quem recebe é de até 5 minutos. |
X-Nonce | Texto aleatório de 16 a 128 caracteres, novo a cada pedido. Na resposta de um callback, devolva o mesmo nonce que recebeu. |
X-Idempotency-Key | Só 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-Signature | A 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).
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.
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.
/backend/v1/operator/gamesresponde 200Envie 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.
{
"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.
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.
/backend/v1/operator/sessionsresponde 201Envie os cabeçalhos de assinatura, sem X-Idempotency-Key.
Pedido
| Campo | Tipo | Descrição |
|---|---|---|
external_session_id | texto, 1–128 | O identificador da sessão no seu sistema. Único por operador. |
player_id | texto, 1–128 | O identificador do jogador no seu sistema. Volta em todos os callbacks. |
game_id | texto | O ID de um dos jogos liberados para você. |
balance_units | inteiro ≥ 0 | O 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
{
"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"
}| Campo | Descrição |
|---|---|
session_id | O 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_url | A URL que abre o jogo para este jogador. Veja Abrir o jogo. |
expires_at | Quando 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_iddevolve 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. Obalance_unitsda 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":"…"}.
| Status | error | Causa |
|---|---|---|
| 400 | invalid JSON | JSON malformado, campo desconhecido, tipo errado (por exemplo game_id numérico) ou corpo acima de 64 KB. |
| 401 | invalid signature | Cabeçalho ausente, operador desconhecido, timestamp fora dos 5 minutos, nonce fora de 16–128 caracteres ou assinatura que não confere. |
| 402 | ggr credit exhausted | Sua 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. |
| 403 | game disabled | O jogo não está liberado para o seu operador, ou o operador está desativado. |
| 409 | conflict | Campo 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. |
| 500 | internal error | Falha do nosso lado. Repita com timestamp e nonce novos. |
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ão | Uma sessão é de um jogador em um jogo. Para outro jogo, abra outra sessão. |
| Validade | 12 horas. Para continuar depois disso, repita a abertura com o mesmo external_session_id ou abra uma sessão nova. |
| Saldo na tela | O 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órico | O histórico dentro do jogo mostra as rodadas daquela sessão. |
| Página inteira | O jogo foi verificado aberto como página de nível superior. O uso dentro de iframe não foi homologado. |
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.
https://sua-carteira/…a URL que você cadastrouOs quatro eventos
| Evento | Quando chega | O que fazer |
|---|---|---|
bet | Uma vez, quando a rodada abre. | Debite amount_units do saldo do jogador, ou recuse a aposta. |
prize | Só quando a rodada paga. | Credite amount_units. Não pode ser recusado. |
reconciliation | Sempre, por último. Fecha a rodada. | Não mexa no saldo. Marque a rodada como encerrada e confira os totais. |
refund | Só quando cancelamos uma rodada cuja aposta nunca foi confirmada. | Devolva a aposta, se você a debitou. Veja Cancelamento e refund. |
A ordem dos eventos
| Rodada | Eventos, nesta ordem |
|---|---|
| Sem prêmio | bet → reconciliation |
| Com prêmio | bet → prize → reconciliation |
| Aposta recusada por você | bet, respondido com 409. Nenhum outro evento. |
| Cancelada por nós | bet 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 umprizepor 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
beteprizeestão confirmados. Areconciliationvem 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
reconciliationda 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.
{
"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:
{
"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.
| Campo | Tipo | Descrição |
|---|---|---|
event | texto | bet, prize, reconciliation ou refund. |
transaction_id | texto | Identificador único do evento. Repetições do mesmo evento trazem o mesmo valor. Os prêmios são numerados a partir de 1. |
round_id | texto | A rodada. Todos os eventos de uma rodada têm o mesmo round_id. |
session_id | texto | O session_id que a abertura de sessão devolveu. |
player_id | texto | O player_id que você informou na abertura. |
game_id | texto | O jogo da sessão. |
amount_units | inteiro ≥ 0 | O valor que o evento movimenta: a aposta em bet, o prêmio em prize, a aposta a devolver em refund. Sempre 0 na reconciliation. |
currency | texto | Sempre BRL. |
total_bet_units | inteiro ≥ 0 | Só na reconciliation: o valor da aposta da rodada. Em rodada cancelada, o mesmo valor de total_refund_units. |
total_prize_units | inteiro ≥ 0 | Só na reconciliation: a soma dos prêmios da rodada. Zero quando ela não pagou. |
total_refund_units | inteiro ≥ 0 | Só na reconciliation: o valor devolvido em uma rodada cancelada. Zero nas outras. |
ggr_units | inteiro | Só 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ção | Status | Corpo | Efeito |
|---|---|---|---|
| Evento registrado | 200 | {"ok":true,"balance_units":996000} | Confirmado. balance_units é o saldo do jogador depois do evento. |
| Aposta recusada | 409 | {"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 todo200, como inteiro igual ou maior que zero. Nareconciliation, envie o saldo atual. Um saldo ausente ou nulo deixa o evento pendente.- O
409assinado é a única forma de recusar uma aposta. Use-o também para jogador bloqueado ou limite atingido. Outro4xxou5xxnão cancela nada: a aposta continua sendo reenviada. - A resposta ao
refundleva um campo a mais, o reciborefunded_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
beteprizecom os rolos girando, então mire em bem menos de um segundo. - HTTPS com certificado válido e sem redirecionamento: uma resposta
3xxnã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.
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_idcom restrição de unicidade, na mesma transação de banco que altera o saldo. - Ao receber um
transaction_idque 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 o409de recusa em umabet. - Resposta sem
X-Signatureválida, comX-Noncediferente do pedido ou comX-Timestampmais de 5 minutos fora. - Corpo que não é o JSON esperado,
okfalso em um200, oubalance_unitsausente, nulo ou negativo. - Em um
refund, resposta semrefunded_unitsou com valor diferente de zero e da aposta.
Quando reenviamos
| Quando | O que fazemos |
|---|---|
| Primeira falha | Nova tentativa em 1 segundo. A cada falha a espera dobra, até 256 segundos. |
| Carteira sem responder | As 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 evento | A rodada é marcada para atenção e a nossa equipe é alertada. As tentativas continuam. |
| 24 horas sem confirmação | As 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
betouprizeestã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
reconciliationpendente 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.
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 carteira | O que fazer | refunded_units |
|---|---|---|
| Você debitou a aposta daquela rodada | Credite amount_units de volta e responda 200 com o novo saldo. | O valor da aposta |
| A aposta nunca chegou, ou você a recusou | Não credite nada e responda 200 com o saldo atual. | 0 |
{ "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 orefundé reenviado.- Guarde o
refund. Se abetdaquela rodada chegar depois dele, por um pedido atrasado na rede, não debite: responda com o409de 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 refund | total_bet_units | total_refund_units |
|---|---|---|
refunded_units igual à aposta | A aposta | A aposta |
refunded_units igual a 0 | 0 | 0 |
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_unitsque você recebe no callbackreconciliation. - O crédito é contado em GGR, por categoria de jogo:
slotselive(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
402e 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:
crédito = pagamento ÷ taxa
credit_units = amount_units × 10000 ÷ ggr_rate_bps (arredondado para baixo ao centavo)| Taxa | Você paga | Crédito de GGR |
|---|---|---|
| 5% | R$ 5.000,00 | R$ 100.000,00 |
| 5% | R$ 100,00 | R$ 2.000,00 |
| 8% | R$ 5.000,00 | R$ 62.500,00 |
| 12,5% | R$ 1.000,00 | R$ 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
/backend/v1/operator/billingresponde 200Assine como o catálogo: método GET, o caminho acima, sem corpo e sem parâmetros, com nonce novo.
{
"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
}| Campo | Significado |
|---|---|
prepaid | Se a sua operação é pré-paga. Com false, ignore o resto. |
ggr_rate_bps | A taxa em centésimos de por cento: 500 é 5%. null significa que a categoria não é vendida nem cobrada. |
ggr_rate_percent | A mesma taxa em texto, para exibir. |
credit_units | O crédito de GGR que resta, em unidades de R$ 0,0001. Pode ficar negativo até o limite. |
negative_limit_units | Até quanto o crédito pode ficar negativo antes do bloqueio. É definido pela nossa equipe. |
blocked | true quando credit_units + negative_limit_units é zero ou menos: os jogos da categoria não aceitam aposta nova. |
credit_per_real_units | Quanto crédito R$ 1,00 compra na taxa atual. A 5%, 200000 (R$ 20,00). |
purchases_available | Se você consegue gerar um PIX agora. |
min_amount_units, max_amount_units | O 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
/backend/v1/operator/billing/purchasesresponde 201Envie os cabeçalhos de assinatura, sem X-Idempotency-Key, como na abertura de sessão.
| Campo | Tipo | Descrição |
|---|---|---|
purchase_id | texto | O 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. |
category | texto | slots ou live. A categoria precisa ter taxa. |
amount_units | inteiro | Quanto 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. |
{"purchase_id":"compra-2026-11-0001","category":"slots","amount_units":50000000}{
"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_unitsjá é 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 exibaqr_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
/backend/v1/operator/billing/purchases/{purchase_id}responde 200Assine 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.
| status | Significado |
|---|---|
creating | O PIX ainda está sendo gerado. Consulte de novo em instantes. |
pending | Aguardando o pagamento. Só neste estado a resposta traz o código e a imagem do PIX. |
paid | Pago e creditado. paid_at tem a hora. |
expired | Não foi pago a tempo. Faça outra compra, com outro purchase_id. |
failed | O PIX não pôde ser gerado. Faça outra compra, com outro purchase_id. |
reversed | O 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
| Status | error | Causa |
|---|---|---|
| 401 | invalid signature | Assinatura, timestamp ou nonce inválidos. |
| 403 | game disabled | O operador está desativado. |
| 404 | not found | Não existe compra sua com esse purchase_id. |
| 409 | conflict | Nonce 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. |
| 409 | prepaid billing is not available | A 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ê. |
| 429 | too many open purchases | Já 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.
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
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
\nseguidos 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_idjá pertence a uma sessão de outro jogador ou de outro jogo. - O
game_idnã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-Nonceda resposta diferente do nonce do pedido.- Status
201,204ou outro2xxno lugar de200. - 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.