Devoluções, estornos e disputas¶

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

Esta página separa o que existe de verdade em produção do que só existe no sandbox: devolução de depósito, devolução de saque pelo banco, estorno, chargeback e disputa. Cada caso tem um efeito diferente no caixa da operação e no seu livro. Construa o seu conector para todos eles, mas não espere os eventos de estorno e chargeback em produção.

O que é¶

Caso	Estado	Produção	Sandbox
Depósito devolvido pelo revisor	deposit em returned	Existe	Existe
Saque devolvido pelo banco depois de pago	withdrawal em returned	O mecanismo existe. O guia não afirma quais PSPs informam devolução hoje	Existe, por ação de sandbox
Estorno de depósito pago	deposit em refunded	Sem gatilho	Existe
Chargeback ou MED de depósito pago	deposit em chargeback	Sem gatilho	Existe
Disputa de cartão	Nenhum	Não disponível	Não disponível
Recall de saque	recalled	Não ocorre em PIX	Não ocorre em PIX

"Sem gatilho" quer dizer: o estado e o tratamento no caixa existem no Dracma, mas nenhum PSP nem rotina da produção leva um depósito até lá hoje. Teste o seu tratamento no sandbox.

Quando usar¶

Leia esta página ao:

• escrever o tratamento de refunded, chargeback e returned no seu conector;
• explicar ao financeiro por que o caixa mudou depois de um depósito que já estava paid;
• decidir a política de débito do jogador (veja Política de exceções de dinheiro).

Como funciona¶

Efeito de cada caso¶

Caso	Caixa da operação (available)	Item no relatório diário	O que fazer no seu livro
Depósito returned	Não muda (nunca foi creditado)	return, pelo valor pago	Nada
Saque returned	Sobe o valor devolvido (pode ser parcial)	return, pelo valor devolvido	Política sua; recomendação: abrir caso, não recreditar sozinho
Depósito refunded	Cai o valor do depósito	refund	Débito conforme a sua política; recomendação: abrir caso
Depósito chargeback	Cai o valor do depósito	chargeback	Idem

Pontos que costumam surpreender:

• Estorno e chargeback debitam o caixa pelo valor cheio. Não há tarifa no movimento (veja Tarifas).
• O caixa livre pode ficar negativo. Se o jogador já sacou e há outros saques reservados, o débito do estorno ou do chargeback pode deixar o caixa livre abaixo de zero. Enquanto isso durar, novos saques recebem 422 insufficient_operation_balance (veja Saldos e caixa livre).
• Depósito returned não debita. Ele nunca passou por paid, então o relatório mostra só o item return e nenhum item deposit para ele.
• Saque devolvido continua com o item withdrawal do dia do pagamento. O item return aparece no dia da devolução; não há compensação automática dentro do total withdrawals_paid (veja Reconciliar com o seu livro).

Por que não mover dinheiro sozinho¶

Um débito automático num jogador que já sacou deixa saldo negativo. Um recrédito automático de um saque devolvido pode pagar duas vezes se o banco reenviar. Esses casos são raros e caros: a recomendação é abrir um caso com alerta e deixar uma pessoa decidir. O modelo está em Política de exceções de dinheiro.

Disputas de cartão¶

Recall¶

POST /v1/withdrawals/{id}/recall só vale para saques por transferência bancária, que o Dracma não oferece. Num saque PIX a rota responde 409 invalid_state_transition sem mudar nada. Os estados recall_requested e recalled e o item recall do relatório são reservados.

Exemplos¶

No sandbox, o estorno e o chargeback saem de um depósito paid:

POST /v1/sandbox/deposits/{id}/refund       -> 200, deposit.refunded
POST /v1/sandbox/deposits/{id}/chargeback   -> 200, deposit.chargeback

Cada ação exige Idempotency-Key e só vale a partir de paid; em qualquer outro estado a resposta é 409. As rotas existem apenas em operação Teste. Use-as para provar que o seu conector não credita nem debita sozinho ao ver refunded e chargeback (receita no Sandbox: receitas).

Para o saque, a ação return de sandbox leva um saque paid a returned, com o objeto return preenchido (veja Ciclo do saque).

Erros e casos de borda¶

• Estado desconhecido. Trate como não terminal. Não mova dinheiro.
• Chargeback depois de saque. O jogador já sacou: o caixa pode ficar negativo e o saldo do jogador no seu livro, também. Registre o caso e decida com uma pessoa.
• Devolução duplicada. Um segundo withdrawal.returned para o mesmo saque não credita o caixa de novo. O seu conector também deve ser idempotente pelo external_id.
• Devolução inválida. Valor zero, maior que o pago ou em outra moeda é recusado pelo Dracma e gera alerta; o saque não muda.

Veja também¶

• Modelo de dinheiro
• Ciclo do depósito
• Ciclo do saque
• Política de exceções de dinheiro
• Reconciliar com o seu livro
• Sandbox: receitas