Estados no seu produto

Para: Dev — Conferido em 2026-10-18.

O jogador não deve ver os estados do Dracma. Ele vê um conjunto menor e estável de estados do seu produto, que o seu conector calcula a partir do último estado do Dracma aplicado. Esta página dá a tabela de tradução (Dracma, seu produto, efeito no seu livro, mensagem) e a regra para calcular o estado sem corrida.

O que é

A regra geral: o estado mostrado ao jogador nunca adianta dinheiro. paid só aparece depois de o crédito do depósito (ou a finalização do saque) estar gravado no seu livro.

Conjunto sugerido de estados do seu produto:

Fluxo Estados do produto
Depósito creating, pending, paid, expired, cancelled, failed, under_review
Saque processing, under_review, paid, rejected, failed, cancelled

Dois itens ajudam a calcular o estado:

  • O estado local do seu registro de envio (por exemplo, uma fila de saída com o pedido ao Dracma).
  • O último estado do Dracma aplicado, lido por fetch-back (GET /v1/deposits/{id} ou GET /v1/withdrawals/{id}).

Quando usar

Use a tabela ao desenhar as telas e o contrato do seu front com o seu back. Troque os nomes dos estados do produto pelos seus; o que importa é a coluna "efeito no seu livro".

Como funciona

Depósito: Dracma para o seu produto

Situação Estado do Dracma (fetch-back) Seu produto mostra Efeito no seu livro Mensagem sugerida
Pedido gravado, chamada sem resposta conclusiva (timeout, 5xx, 429) Nenhum creating Nenhum "Gerando seu PIX..."
202 do Dracma created creating Nenhum "Gerando seu PIX..."
PIX gerado pending pending, com o copia-e-cola Nenhum "Pague o PIX até {hora}."
Pagamento em análise under_review under_review Nenhum "Pagamento recebido, em análise."
Crédito gravado paid paid Credita uma vez "Depósito confirmado."
Prazo vencido expired expired Nenhum "O PIX expirou. Gere outro."
Cancelado cancelled cancelled Nenhum "Depósito cancelado."
Não foi possível gerar o PIX failed failed Nenhum "Não foi possível gerar o PIX. Tente de novo."
Devolvido em revisão returned failed Nenhum "O pagamento não pôde ser aceito. Fale com o suporte."
Já creditado, depois estorno ou chargeback refunded ou chargeback paid (continua) Não mexe: abre caso Nenhuma ao jogador; o caso é tratado internamente
Estado do contrato que o PIX não usa pending_compliance, frozen, paid_partial under_review Nenhum "Pagamento em análise."
Estado desconhecido Qualquer outro Mantém o último estado mostrado (ou under_review se era pending) Nenhum "Pagamento em análise."
Recusa 4xx na criação Sem objeto Erro para o front Nenhum Mensagem genérica de erro
Dracma indisponível ou não configurado Sem objeto Erro 503 do seu produto Nenhum "Depósito indisponível no momento."

Saque: Dracma para o seu produto

Situação Estado do Dracma (fetch-back) Seu produto mostra Reserva no seu livro Mensagem sugerida
Pedido e reserva gravados, sem resposta conclusiva Nenhum processing Mantida "Saque em processamento."
Chave PIX em consulta requested processing Mantida "Saque em processamento."
Aprovado ou em envio approved, processing processing Mantida "Saque em processamento."
Em revisão under_review under_review Mantida "Saque em análise."
Finalização gravada paid paid Finalizada (saída definitiva) "Saque enviado."
Recusado rejected rejected Devolvida "Saque não aprovado. O valor voltou para sua carteira."
Falhou failed failed Devolvida "Não foi possível enviar o PIX. O valor voltou para sua carteira."
Cancelado cancelled cancelled Devolvida "Saque cancelado. O valor voltou para sua carteira."
Já finalizado, banco devolveu returned under_review Não mexe: abre caso "Saque em análise."
Estados do contrato que o PIX não usa pending_compliance, sent, in_transit, recall_requested processing Mantida "Saque em processamento." (nunca diga "compliance")
Estado reservado recalled under_review Não mexe: abre caso "Saque em análise."
Estado desconhecido Qualquer outro processing Mantida "Saque em processamento."
Recusa 4xx na criação (422, 400) Sem objeto Erro de negócio no seu produto Devolvida Mensagem do seu produto
409 idempotency_key_reused no envio Sem objeto processing Mantida: abre caso "Saque em processamento."

Mensagens ao jogador

  • Nunca explique under_review com o motivo (PAYER_MISMATCH, AMOUNT_MISMATCH, FIRST_WITHDRAWAL...). O suporte vê o motivo; o jogador, não.
  • Devolução de depósito. returned não existe na lista de estados do produto: mostre failed com a mensagem de pagamento não aceito. Evite afirmar como o dinheiro volta ao pagador; encaminhe ao suporte.
  • Devolução de saque. returned aparece depois de o jogador ter visto paid: mostre "Saque em análise" e abra um caso. Se o seu suporte recreditar o jogador, peça a ele para cadastrar outra chave.
  • Nunca diga "compliance", "sanção" ou "lista" ao jogador, mesmo que o estado do contrato os mencione.

Como calcular o estado sem corrida

estado_do_produto(registro):
  se registro.versao_dracma é nula:            # o Dracma ainda não respondeu de forma conclusiva
      devolva "creating" (depósito) ou "processing" (saque)
  s = registro.estado_dracma                    # último estado APLICADO, por fetch-back
  devolva TABELA[s] ou PADRAO_DESCONHECIDO
  • Aplique um estado novo só se a version for maior que registro.versao_dracma. Webhooks chegam fora de ordem.
  • O efeito no dinheiro e a atualização de estado_dracma vão na mesma transação do seu banco. Assim o seu front nunca vê paid antes do crédito.
  • O polling do front não deve chamar o Dracma a cada pedido. Leia o seu banco. Se um registro está parado em creating ou pending há mais de cerca de 60 segundos, faça um fetch-back por id (no máximo a cada 10 segundos por objeto), além do webhook e do job de GET /v1/events.

Exemplos

Um depósito do ponto de vista do jogador:

Instante Dracma Seu produto Jogador vê
15:00:00 POST /v1/deposits sem resposta (timeout) creating "Gerando seu PIX..."
15:00:02 pending, version 2 pending QR code e copia-e-cola
15:03:10 paid, version 3 paid (depois do crédito gravado) "Depósito confirmado."

Erros e casos de borda

  • Estado desconhecido nunca move dinheiro. Mantenha a reserva do saque e não credite o depósito.
  • refunded e chargeback acontecem depois de o jogador ter visto paid. A tela não volta atrás; o caso vai para a fila de exceções (veja Política de exceções de dinheiro).
  • Um depósito expired, cancelled ou failed com paid_amount preenchido é pagamento tardio: não credite.

Veja também