Ciclo do depósito¶

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

Um depósito é uma cobrança PIX que o jogador paga. O Dracma só leva o depósito a paid quando o pagamento confere com o que você pediu, e só então o caixa da operação cresce. Esta página mostra os estados, o efeito de cada um no seu livro e o que fazer com pagamento fora do prazo, divergente ou devolvido.

O que é¶

O depósito passa por estas transições. paid é terminal para o crédito, mas ainda pode ir a refunded ou chargeback.

• Terminais: expired, cancelled, failed, returned, refunded e chargeback.
• version começa em 1 em created e sobe a cada transição. Ignore qualquer estado cuja version seja menor ou igual à que você já aplicou.
• O primeiro estado que você costuma ver é pending, com version 2.
• Os estados pending_compliance, frozen e paid_partial fazem parte do contrato, mas nenhum caminho do PIX leva um depósito até eles hoje. Se aparecerem, não mova dinheiro e confira de novo (leitor tolerante).

Quando usar¶

Use esta página para decidir quando creditar o jogador e como tratar o que foge do caminho feliz. A regra que não muda:

1. Só paid credita.
2. Credite uma vez, pelo valor que você registrou na criação. Em paid, paid_amount é sempre igual a amount.
3. A idempotência é pelo external_id: dois eventos deposit.paid (reentrega, GET /events, corrida) creditam uma vez só.
4. Leia o estado pela API (GET /v1/deposits/{id}) antes de creditar. O corpo do webhook não autoriza crédito.

Como funciona¶

Do pedido ao pagamento¶

A notificação do PSP só dispara a conferência: o Dracma consulta o PSP antes de agir. Para a decisão de paid, o Dracma confere quatro coisas:

O motor de regras também pode mandar o pagamento para revisão (por exemplo PAYER_BLOCKED). Se o motor estiver fora do ar ou devolver resposta incoerente, o depósito vai para revisão com RULES_UNAVAILABLE ou RULES_INVALID_RESPONSE: na dúvida, uma pessoa decide.

Efeito no seu livro¶

Quando o depósito chega a paid, o caixa da operação sobe o valor cheio na hora. Não há tarifa descontada do crédito (veja Tarifas).

Revisão: quem decide e como¶

Deposito.review_reasons lista por que o depósito está em under_review. A decisão é de um revisor no painel, que registra o motivo (veja Painel: revisão).

As duas decisões possíveis:

• Aceitar: under_review vai a paid. O Dracma grava paid_amount igual a amount se estiver vazio e libera o crédito do caixa. AMOUNT_MISMATCH não pode ser aceito: o único caminho é devolver.
• Devolver: under_review vai a returned.

O campo payer (em paid e under_review) traz document, name e matches_player. Use-o só para exibir e auditar; a decisão de crédito é o status.

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "under_review",
  "version": 3,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": { "amount": "4000", "currency": "BRL" },
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "payer": {
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" },
    "name": "Jogador Teste",
    "matches_player": true
  },
  "instructions": null,
  "failure_code": null,
  "review_reasons": ["AMOUNT_MISMATCH"],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:04:10Z",
  "paid_at": "2026-10-18T15:04:09Z",
  "expires_at": "2026-10-18T15:30:00Z"
}

returned: o que significa¶

returned é o desfecho em que o revisor recusou o crédito. Para o seu livro, o efeito é nenhum: o depósito nunca foi creditado e o caixa da operação não muda. O relatório diário lista o depósito como item return (veja Reconciliar com o seu livro).

Expiração¶

• expires_in_seconds aceita de 300 a 86400. O padrão é 1800 (30 minutos).
• O Dracma expira o depósito pending 2 minutos depois de expires_at. A folga existe porque o PSP ainda pode aceitar um pagamento logo depois do prazo. Um job a cada 30 segundos faz a varredura, e então sai deposit.expired.
• Mostre o copia-e-cola ao jogador até instructions.pix.expires_at, que é o prazo que o PSP aplica.

Prazo por PSP¶

Cada PSP aplica o próprio limite de prazo da cobrança:

Quando o PSP muda o prazo, o valor que vale para o jogador vem em instructions.pix.expires_at. O campo expires_at do depósito guarda o prazo que você pediu e é com ele que o Dracma decide expirar. Com Mercado Pago, não peça menos de 31 minutos (1860 segundos): com um prazo curto, o PSP mantém a cobrança pagável por mais tempo que o Dracma, e um pagamento nessa janela cai em "pagamento tardio" (abaixo).

Exemplos¶

Pagamento tardio: o PIX foi pago depois de o depósito ter expirado. O estado não muda; o Dracma grava o que recebeu.

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "expired",
  "version": 3,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": { "amount": "5000", "currency": "BRL" },
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "payer": {
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" },
    "name": "Jogador Teste",
    "matches_player": true
  },
  "instructions": null,
  "failure_code": null,
  "review_reasons": [],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:40:00Z",
  "paid_at": "2026-10-18T15:39:00Z",
  "expires_at": "2026-10-18T15:30:00Z"
}

Regra de leitura: status é expired, mas paid_amount e paid_at estão preenchidos. Não credite e abra um caso needs_decision.

Erros e casos de borda¶

Pagamento depois do prazo ou do cancelamento¶

Para você, no segundo caso: não credite (o estado é terminal sem crédito) e abra um caso em needs_decision ao ver paid_amount num depósito terminal.

Cancelar não cancela no PSP¶

POST /v1/deposits/{id}/cancel só vale em pending e muda apenas o estado no Dracma. O PIX continua pagável até o prazo do PSP. Um pagamento depois disso cai na regra do pagamento tardio. Em created, espere pending e cancele depois; em qualquer outro estado a resposta é 409 invalid_state_transition.

Falha na criação¶

failed com failure_code mostra o motivo técnico: psp_unavailable (o PSP não respondeu), psp_rejected (o PSP recusou) ou environment_guard (o PSP devolveu algo que o Dracma recusa entregar). É uma lista aberta; o status é que manda.

Estorno e chargeback¶

A máquina e o caixa já tratam refunded e chargeback, mas hoje o gatilho existe só no sandbox. Veja Devoluções, estornos e disputas.

Veja também¶

• Modelo de dinheiro
• Saldos e caixa livre
• Referência: depósitos
• Política de exceções de dinheiro
• Estados no seu produto
• Painel: revisão de depósitos e saques