Cobrança de teste¶

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

Na tela Cobrança de teste você gera um depósito PIX da operação pelo próprio painel, sem escrever código, e acompanha o QR, o estado, os eventos e as entregas de webhook. Em operação de Teste a cobrança é simulada e você pode simular o pagamento. Em operação Real a cobrança é de verdade e pode ser paga.

O que é¶

A tela cria um depósito PIX pelo mesmo serviço que atende POST /v1/deposits. Por isso a cobrança segue as mesmas regras, passa pela decisão (pode ir para revisão) e gera os mesmos eventos. O que a diferencia:

• o external_id do depósito começa com painel-teste-;
• o jogador recebe uma referência painel-teste-…, derivada do documento informado (o mesmo documento gera sempre a mesma referência);
• a lista mostra as últimas 50 cobranças criadas pela tela.

Quem usa: Administrador do tenant e Financeiro. Revisor e Auditor recebem "Não encontrado".

	Operação de Teste	Operação Real
Aviso da tela	"Operação sandbox: a cobrança é simulada e você poderá simular o pagamento."	"Operação de PRODUÇÃO: a cobrança gerada aqui é REAL e pode ser paga de verdade."
Dinheiro	Nenhum se move.	Move dinheiro real.
Simular pagamento	Disponível.	Não existe.
Confirmação extra	Não.	Caixa "Entendo que esta cobrança é REAL e gera um PIX de verdade".
Teto de valor	Nenhum.	Nenhum.

Quando usar¶

• Para ver um depósito andar de ponta a ponta antes de ter o conector pronto.
• Para gerar um evento real e testar o seu receptor de webhook (veja Webhooks no painel, aba Entregas).
• No go-live: a primeira transação real de valor mínimo pode ser feita aqui, numa operação Real (veja De Teste para Real).

Como fazer¶

Gerar a cobrança¶

1. Em Nova cobrança, preencha:
   • Valor (R$): maior que zero, com até 2 casas. Aceita 10, 10,5, 1.234,56 e 10.50.
   • Nome do pagador: de 2 a 120 caracteres.
   • CPF ou CNPJ do pagador: com ou sem máscara; os dígitos verificadores são conferidos.
   • E-mail do pagador: opcional. Algumas operações o exigem.
   • Motivo: de 10 a 1000 caracteres.
2. Em operação Real, marque a confirmação de que a cobrança é real.
3. Clique em Gerar cobrança. É preciso confirmação recente de identidade.
4. O painel abre o detalhe da cobrança.

Fora da instância de produção, o e-mail do pagador precisa usar um domínio reservado (.test, .invalid ou .example); caso contrário a tela mostra "e-mail do pagador: use um e-mail de domínio de teste". Para gerar documentos de teste válidos, veja Dados de teste.

Acompanhar e simular o pagamento¶

O detalhe mostra:

• Resumo: estado, valor, valor pago (se houver), ambiente (Sandbox (simulado) ou Produção (REAL)), referência, criação, expiração e pagamento.
• Pagamento PIX: o QR e o código copia e cola, com botão de copiar, enquanto o depósito não terminou.
• Linha do tempo: os eventos deposit.* do depósito, do mais antigo para o mais novo.
• Entregas de webhook desses eventos: o resultado de cada envio para a sua URL.

A página se atualiza sozinha a cada 3 segundos, com a aba visível, até o estado ficar final (paid, expired, cancelled, failed, returned, refunded ou chargeback). Você pode desmarcar Atualizar sozinho a cada 3 s ou usar Atualizar agora.

Em operação de Teste, enquanto o depósito não terminou, aparece o botão Simular pagamento. Ele exige confirmação recente e leva o depósito a paid, como se o pagador tivesse pago. O painel confirma com "Pagamento simulado. O status atualiza sozinho."

Estados que a tela mostra:

Estado	Rótulo
pending	Aguardando pagamento
under_review	Em revisão
paid	Pago
expired	Expirado
cancelled	Cancelado
failed	Falhou
returned	Devolvido
refunded	Reembolsado
chargeback	Chargeback

Um depósito Em revisão aparece na fila da Revisão. O ciclo completo está em Ciclo do depósito.

O que o seu sistema recebe¶

A cobrança de teste é um depósito de verdade para o Dracma: o webhook da operação recebe os eventos deposit.* dela, com external_id começando por painel-teste-. O seu sistema não criou esse depósito, então o receptor deve ignorar com segurança eventos de external_id desconhecido e responder 2xx, sem tratar como erro. Veja Receptor passo a passo.

Exemplos¶

Cobrança de teste com dados fictícios:

Campo	Valor
Valor (R$)	10,50
Nome do pagador	Pessoa de Teste
CPF ou CNPJ	um CPF de teste válido
E-mail do pagador	pagador@exemplo.test
Motivo	Validar o receptor de webhook do ambiente de homologação

Roteiro de um teste do receptor:

1. Gere a cobrança.
2. Clique em Simular pagamento.
3. Na linha do tempo, veja deposit.pending e deposit.paid.
4. Em Entregas de webhook, confirme o código 2xx de cada um.

Erros e casos de borda¶

Mensagem	Causa	O que fazer
"Informe um valor maior que zero, em reais, com até 2 casas decimais (ex.: 10,50)."	Valor inválido (valor_invalido).	Corrija.
"Informe o nome do pagador (2 a 120 caracteres)."	Nome curto ou longo.	Corrija.
"CPF ou CNPJ inválido. Confira os dígitos."	Documento mal formado ou com dígito verificador errado.	Use um documento válido.
"E-mail inválido."	Formato do e-mail.	Corrija.
"A operação exige dados adicionais do pagador (por exemplo e-mail). Confira os campos."	A operação exige um campo que a tela não preencheu (requisitos).	Preencha o que a lista abaixo da mensagem pedir.
"Escreva um motivo de 10 a 1000 caracteres."	Motivo curto ou longo.	Corrija.
"confirmação de cobrança real: obrigatório"	Falta a caixa de confirmação numa operação Real.	Marque a caixa.
"Confirme com o fator forte (\"Confirmar identidade agora\") e tente de novo."	step_up_required.	Use o link e repita.
"Simular pagamento só existe em operações sandbox."	sandbox_only.	Use a operação de Teste.
"A cobrança mudou de estado e a ação não se aplica mais."	O depósito já terminou.	Recarregue.
"Cobrança não encontrada nesta operação."	Identificador de outra operação ou inexistente.	Volte à lista.
"O serviço está indisponível agora. Tente de novo em instantes."	Dependência fora do ar.	Repita em instantes.

Casos de borda:

• A tela exige dados que ela não tem. Se a operação exigir o IP ou o identificador de dispositivo do jogador, a tela avisa "a tela não envia este dado; ajuste a exigência da operação" e não consegue gerar a cobrança. Use a API para esse caso.
• Cobrança em revisão ou recusada pelas regras. É um depósito normal: acompanhe em Revisão ou em Transações.
• Entregas "indisponíveis". Se o serviço de webhooks estiver fora, o bloco de entregas fica vazio, mas o resto da tela segue funcionando.

Veja também¶

• Webhooks no painel
• Revisão
• Primeiro depósito e primeiro saque
• Depósitos