Saldo no servidor de jogo

Com o crédito ligado numa loja de servidor de jogo, a loja dentro do jogo mostra o saldo do jogador, vende os pacotes de recarga pelo Pix e deixa pagar a compra com o saldo, sem sair do jogo.

Qual carteira o jogador usa#

Dentro do jogo quem diz quem é o jogador é o servidor, pelo token. A carteira que vale é, nesta ordem:

1. A da conta da loja que o jogador vinculou. O comprador gera um código na área dele (Minha conta > Créditos) e o jogador digita esse código no jogo. Isso prova os dois lados: quem é dono da conta e quem está no servidor. A partir daí o saldo é o mesmo no site e no jogo.
2. A carteira do próprio jogador. Sem vínculo, vale a carteira do cliente que nasce das compras no jogo sem e-mail (o e-mail tipo.id@jogador.invalid, pelo identificador mais estável que o servidor mandou: UUID, license, Steam, Discord e assim por diante).

Uma compra no site com o ID do jogador digitado não liga nada: o ID digitado não prova quem é o jogador, e quem ganharia acesso ao saldo seria outra pessoa.

Quais identificadores contam#

O vínculo e a carteira seguem as contas que valem em qualquer servidor e que o jogo confere no login: license (ou license2) e Steam no FiveM e no RedM, UUID e gamertag no Minecraft. Quando o servidor manda alguma delas, só elas contam. O ID da cidade (vRP, Creative, citizenid) e o nick ficam de fora, porque mudam de dono: outra cidade da mesma loja, um reset da cidade ou um nick trocado dão o mesmo valor a outra pessoa. O Discord também fica de fora quando vem junto: o ID dele é público.

• O ID, o nick e o Discord só contam quando o servidor não manda nenhuma conta global.
• Vínculo antigo feito só pelo ID, pelo nick ou pelo Discord deixa de valer quando o servidor passa a mandar uma conta global do jogador. Ele vincula de novo, com um código novo.
• O histórico de pedidos da loja do jogo (POST /shop/history) segue a mesma regra: cada jogador vê só os pedidos da conta global dele.

O vínculo por código#

• O código tem 8 letras e números (ABCD-EFGH), vale 15 minutos e uma vez só. Gerar outro cancela o anterior, e cada conta gera no máximo 6 por hora.
• As contas globais que o servidor atestou passam a apontar para a conta (o ID, o nick e o Discord só quando não vem nenhuma). Um identificador aponta para uma conta só: digitar o código de outra conta troca o vínculo.
• O saldo que o jogador já tinha na carteira dele passa para a conta, com uma entrada de Transferência nos dois extratos.
• Se uma recarga que passou para a conta for reembolsada ou contestada depois, o que a carteira do jogador não cobre sai da conta, até o valor que passou. A conta pode ficar com dívida e não gasta até ser acertada.
• Carteira do jogador com dívida não vincula até a dívida ser acertada. Senão bastaria vincular para sair dela.
• O cliente desfaz o vínculo na área dele. O jogador volta a usar a própria carteira.

Recarga e compra no jogo#

• Recarga: os pacotes vêm em credit.packages do catálogo e são pagos pelo Pix normal (POST /shop/orders). O saldo cai na carteira que o jogador usa no jogo, seja qual for o e-mail digitado.
• Compra com o saldo: POST /shop/credit/orders. O pedido sai pago na hora (ou em revisão, se o antifraude da loja segurar) e a entrega entra na fila do servidor como numa compra por Pix.
• Produto por assinatura pago com o saldo dentro do jogo pede a conta vinculada: o link de cada renovação chega por e-mail.

O que a compra com saldo exige#

Segurança#

• O token de um servidor só enxerga a loja dele. Nenhuma rota recebe ID de loja, e um servidor nunca chega à carteira de outra loja.
• O saldo é consultado e debitado com a carteira travada no banco: duas compras ao mesmo tempo nunca gastam o mesmo saldo.
• O servidor atesta o jogador, então um servidor comprometido poderia gastar o saldo de um jogador da própria loja. A compra é entregue ao mesmo jogador, e o teto por minuto limita o estrago. Se o token vazar, troque em Servidor > Servidores: o antigo para na hora. Para tirar o risco de vez, desligue Gastar no jogo.

Rotas#

Endereço base, com o token do servidor no cabeçalho Authorization: Bearer psg_... (ou X-Promisse-Token):

https://api.promisse.store/api/v1/game

Valores em centavos de real, inclusive o saldo. O nome da moeda e a conversão vêm em name e unit_cents (quantos centavos vale um crédito): para mostrar em créditos, divida o valor por unit_cents.

O player é o mesmo da loja dentro do jogo: { "name": "Steve", "ids": { "license": "license:abc...", "discord": "discord:123..." } }, com os identificadores que o servidor leu do jogador.

Catálogo#

GET /shop ganhou o campo credit, null com o crédito desligado:

{
  "credit": {
    "enabled": true,
    "name": "Coins",
    "unit_cents": 10,
    "game_spend": true,
    "packages": [
      { "id": "…", "name": "Pacote 500", "summary": "", "image_url": null, "price_cents": 5000, "credit_cents": 5500, "bonus_cents": 500, "once_per_buyer": false }
    ]
  }
}

O pacote não aparece em products: ele vai para o carrinho pelo id e é pago em POST /shop/orders, como qualquer produto.

Saldo do jogador#

POST /shop/credit

{ "player": { "name": "Steve", "ids": { "license": "license:abc" } } }

Resposta:

{ "enabled": true, "name": "Coins", "unit_cents": 10, "game_spend": true, "balance_cents": 3000, "blocked": false, "linked": false }

blocked é carteira com dívida (saldo negativo). linked diz se o jogador usa uma conta vinculada. Com o crédito ou a loja do jogo desligados, volta enabled: false.

Cotação com o saldo#

POST /shop/quote aceita "method": "credit". O total_cents vem com o preço do saldo (sem o desconto do Pix), e com o player a resposta traz:

{ "credit": { "enabled": true, "name": "Coins", "unit_cents": 10, "game_spend": true, "balance_cents": 3000, "blocked": false, "linked": false, "available": true, "reason": null } }

reason é o motivo pronto para mostrar quando available é falso: saldo insuficiente, carteira bloqueada, recarga no carrinho ou gasto no jogo desligado.

Comprar com o saldo#

POST /shop/credit/orders

{
  "items": [{ "product_id": "…", "quantity": 1 }],
  "player": { "name": "Steve", "ids": { "license": "license:abc" } },
  "coupon": null,
  "ip": "200.1.2.3",
  "accept_terms": true,
  "age_confirmed": true
}

Resposta 201:

{
  "order": { "id": "…", "number": 42, "status": "paid", "delivered": false, "total_cents": 1990, "expires_at": "2026-11-04T18:30:00.000Z", "paid_at": "2026-11-04T18:00:00.000Z", "link": "https://…/order/…?t=…" },
  "balance_cents": 1010,
  "blocked": false
}

Os itens seguem as mesmas regras de /shop/orders: até 20 linhas, 1000 unidades por linha e os campos extras do produto.

Vincular a conta#

POST /shop/credit/link

{ "player": { "name": "Steve", "ids": { "license": "license:abc" } }, "code": "ABCDEFGH" }

O código aceita com ou sem o hífen. Resposta:

{ "linked": true, "email": "ma*****@gmail.com", "balance_cents": 4000 }

Benefícios do jogador#

POST /benefits devolve os benefícios com prazo do jogador, o que o /vip mostra no jogo. Ele recebe o mesmo player das outras rotas e segue a regra de Quais identificadores contam: com license, Steam, UUID ou gamertag, só aparecem as compras dessa conta, e o ID da cidade repetido em outra cidade da loja não mostra o VIP de outra pessoa.

{ "player": { "name": "Steve", "ids": { "id": "808", "license": "license:abc" } } }

Resposta:

{ "benefits": [{ "product_name": "VIP Ouro", "expires_at": "2026-12-04T18:00:00.000Z" }] }

O GET /benefits?player=<identificador>, um identificador por consulta, continua valendo para os scripts que perguntam assim. As duas formas dividem o balde dos comandos dos jogadores (240 por minuto).

Erros#

Os limites por token: /shop/credit divide o balde da loja do jogo (180 por minuto), /shop/credit/orders tem 60 a cada 10 minutos e /shop/credit/link tem 30 a cada 10 minutos.

Scripts que já mostram o saldo#

Em qualquer jogo, o pedido pago com saldo pelo site chega à fila do servidor como um pedido pago por Pix: o script de entrega não precisa mudar.

Para levar o saldo a outro script, use as rotas acima com os mesmos cuidados da loja do FiveM: os identificadores sempre lidos do servidor, nunca do que o jogador digitou, e um limite por jogador antes de chamar a compra.