Modelo de dinheiro

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

O Dracma mantém, para cada operação, um caixa próprio em BRL. O depósito pago aumenta esse caixa na hora; o saque o reserva no envio e o consome quando o PIX sai. Esta página mostra quando o dinheiro se move, o que move o saldo e o efeito de cada estado no seu livro.

O que é

Três livros convivem numa operação. Só dois deles são seus de ler.

Livro De quem é O que registra Você lê por
O seu Você (o conector) Carteira do jogador e reservas de saque O seu banco de dados
O do Dracma Dracma, um por operação e moeda Caixa da operação: o que entrou por depósito pago, o que está reservado e o que já saiu GET /v1/balances
O do PSP O PSP (Mercado Pago, MaximaxPay) Conta bancária onde o PIX entra e sai Não é exposto

O caixa do Dracma é uma posição contábil, não o saldo bancário do PSP:

  • O depósito vira caixa quando o Dracma o marca como paid. O Dracma não espera nenhuma liquidação bancária adicional e não existe prazo D+N visível na API.
  • O Dracma nunca mostra o saldo da conta do PSP. GET /v1/balances descreve apenas a posição da sua operação.

Valor cheio

O crédito de um depósito paid é o valor cheio do depósito. O Dracma não desconta tarifa desse crédito. Veja Tarifas.

Quando usar

Leia esta página antes de:

Como funciona

Quando o dinheiro se move

No depósito, o caixa cresce no instante em que o depósito chega a paid. No saque, o caixa é reservado quando o Dracma envia o pedido ao PSP e consumido quando o PIX é liquidado.

sequenceDiagram autonumber participant J as Jogador participant C as Seu conector participant D as Dracma participant P as PSP C->>D: POST /v1/deposits D->>P: cria a cobrança PIX D-->>C: 201, PIX copia-e-cola (pending) J->>P: paga o PIX P-->>D: notificação de pagamento D->>P: confere o pagamento Note over D: depósito paid: o caixa da operação cresce pelo valor cheio D-->>C: deposit.paid (você lê por GET e credita o jogador) C->>D: POST /v1/withdrawals (reserva já feita no seu livro) D-->>C: 201 (approved ou under_review) Note over D: no envio ao PSP: reserva no caixa (pending_out sobe) D->>P: pede o PIX P-->>D: PIX liquidado Note over D: withdrawal paid: a reserva vira saída definitiva D-->>C: withdrawal.paid (você finaliza a sua reserva)

O que move o saldo

Estes são os únicos movimentos do caixa da operação. available e pending_out seguem a coluna de cada um (a leitura de cada campo está em Saldos e caixa livre).

Movimento Quando acontece available pending_out Item no relatório diário
Depósito pago Depósito chega a paid Sobe o valor Não muda deposit
Reserva do saque O Dracma prepara o envio ao PSP Não muda (o reservado continua dentro de available) Sobe o valor Nenhum
Saque liquidado PIX confirmado (paid) Cai o valor Cai o valor withdrawal
Reserva liberada Envio falhou de forma definitiva (failed), saque rejected ou cancelled depois da reserva Não muda Cai o valor Nenhum
Saque devolvido pelo banco returned: o PIX pago voltou Sobe o valor devolvido (pode ser parcial) Não muda return
Estorno ou chargeback de depósito refunded ou chargeback depois de paid Cai o valor Não muda refund ou chargeback
Depósito devolvido em revisão returned (nunca passou por paid) Não muda Não muda return

Três observações:

  • A reserva só existe a partir do envio. Um saque em approved ou under_review ainda não consome pending_out; vários saques aprovados podem somar mais que o caixa livre. Quem não consegue reservar na hora do envio fica approved (veja Ciclo do saque).
  • Estorno e chargeback de depósito só ocorrem no sandbox hoje (veja Devoluções, estornos e disputas).
  • O relatório diário não tem item de tarifa nem de ajuste.

Matriz de estados

Esta é a visão única das duas máquinas: o estado, quem o causa, o efeito no seu livro, o efeito no caixa da operação e o evento de webhook. A coluna "efeito no seu livro" é a recomendação do guia; o Dracma não toca no seu livro.

Depósito

Estado Quem causa Efeito no seu livro Efeito no caixa da operação Evento
created Você, com POST /v1/deposits Nenhum Nenhum Nenhum (o primeiro evento é deposit.pending)
pending Dracma, quando o PSP devolve o PIX Nenhum; mostre o copia-e-cola Nenhum deposit.pending
under_review Dracma, quando há divergência no pagamento Nenhum Nenhum; o valor aparece em pending_in deposit.under_review
paid Dracma (pagamento confere) ou revisor no painel Credita uma vez pelo valor que você registrou available sobe o valor deposit.paid
expired Dracma, depois de expires_at mais uma folga Nenhum Nenhum deposit.expired
cancelled Você, com POST /v1/deposits/{id}/cancel Nenhum Nenhum deposit.cancelled
failed Dracma, quando o PSP recusa ou fica indisponível Nenhum Nenhum deposit.failed
returned Revisor no painel, ao devolver Nenhum Nenhum (nunca houve crédito) deposit.returned
refunded Estorno (só sandbox hoje) Débito conforme a sua política available cai o valor deposit.refunded
chargeback Chargeback ou MED (só sandbox hoje) Débito conforme a sua política available cai o valor deposit.chargeback

Saque

Estado Quem causa Efeito no seu livro Efeito no caixa da operação Evento
requested Dracma, aguardando a consulta da chave PIX Mantém a reserva Nenhum Nenhum
under_review Dracma (regras mandam para revisão) Mantém a reserva Nenhum withdrawal.under_review
approved Dracma (automático) ou revisor Mantém a reserva Nenhum até o envio withdrawal.approved
processing Dracma, no primeiro retorno do PSP Mantém a reserva pending_out com o valor reservado withdrawal.processing
paid Dracma, com o PIX liquidado Finaliza: a reserva vira saída definitiva available e pending_out caem o valor withdrawal.paid
rejected Dracma ou revisor Devolve a reserva ao jogador Nenhum withdrawal.rejected
failed Dracma, com resposta definitiva do PSP Devolve a reserva Reserva liberada withdrawal.failed
cancelled Você, o painel ou uma lista de bloqueio no envio Devolve a reserva Nenhum, ou reserva liberada withdrawal.cancelled
returned Dracma, quando o banco devolve um PIX já pago Política sua; recomendação: não mover dinheiro sozinho available sobe o valor devolvido withdrawal.returned

Estado ou evento desconhecido é não terminal: não mova dinheiro e confira de novo pela API.

Exemplos

Uma operação nova com um depósito de R$ 500,00 pago, um saque de R$ 100,00 liquidado e um saque de R$ 80,00 em envio:

Momento available pending_out Caixa livre
Depois do depósito R$ 500,00 R$ 0,00 R$ 500,00
Reserva do saque de R$ 100,00 R$ 500,00 R$ 100,00 R$ 400,00
Saque de R$ 100,00 liquidado R$ 400,00 R$ 0,00 R$ 400,00
Reserva do saque de R$ 80,00 R$ 400,00 R$ 80,00 R$ 320,00

Erros e casos de borda

Não disponível

O Dracma não oferece aporte de caixa. O caixa da operação só cresce por depósito pago ou por devolução de saque. Não existe rota, painel ou evento para adicionar saldo de outra forma. Enquanto não houver depósitos pagos, o caixa livre é zero e um saque recebe 422 insufficient_operation_balance. Veja Saldos e caixa livre.

  • GET /v1/balances fora do ar responde 503 retryable. Repita depois do Retry-After; nunca decida saque com o último valor lido há muito tempo.
  • O caixa pode ficar negativo para novos saques depois de um estorno, chargeback ou devolução de depósito (veja Saldos e caixa livre).
  • Valores são Money: inteiro na menor unidade, sem float. Veja Convenções HTTP.

Veja também