Erros e Solução de Problemas no SmartForm

Se o formulário não aparecer ou um pagamento não puder ser concluído, identifique primeiro em qual etapa ocorreu a falha: criação da Venda, carregamento do SDK, exibição do formulário ou processamento do pagamento.

Diagnóstico rápido

Sintoma	O que conferir
A API não retorna `smart_form.token`	Verifique resposta completa de `POST /v1/charges`, configurações/contrato da empresa e eventual falha na geração do formulário. Não tente gerar token no frontend.
Formulário não aparece	Verifique se `kr-public-key` e `kr-form-token` foram preenchidos; confira o console, o HTML e os recursos carregados pela PayZen.
Tema Neon não carrega	Confirme se o script `neon.js` e o CSS do tema foram carregados.
Token deixou de funcionar	O token é temporário. Inicie um novo fluxo pelo servidor conforme a situação da Venda; não reutilize indefinidamente o mesmo token.
Uma carteira não aparece	Confirme habilitação no contrato, navegador/dispositivo e os identificadores informados em `payments_supported`.
Pagamento recusado	Exiba a mensagem adequada ao comprador, consulte a Transação e avalie nova tentativa conforme a regra do seu negócio.
Comprador voltou da página de sucesso, mas o pedido não atualizou	Confira `GET /v1/charges/{uuid}`, os estados em `transactions[]` e o recebimento do webhook.
Webhook não chegou	Verifique cadastro e disponibilidade do endpoint receptor, resposta HTTP, tentativas e registros do seu servidor.

Mostrar erros do formulário

Mantenha o elemento disponibilizado pelo tema PayZen para mensagens do SmartForm:

<div class="kr-form-error" role="alert" aria-live="polite"></div>

Aplique estilos ao redor do formulário sem esconder mensagens necessárias ao comprador.

Registro seguro para diagnóstico

Armazene o uuid da Venda, data/hora, etapa e código de erro recebido. Não registre chave secreta api_key, dados completos de cartão, CVV ou o token do formulário em logs públicos.

🚧
Validade do token
A duração exata do form token é A confirmar. Trate a expiração no fluxo do servidor e não presuma um prazo fixo.

Depois de corrigir

Repita o fluxo de criação e renderização no sandbox compatível com o contrato, usando dados sintéticos. Consulte também Segurança e Webhooks.