Segurança, Chaves, Token e Webhooks do SmartForm

O SmartForm separa as responsabilidades da integração de servidor, do formulário apresentado pela PayZen e da confirmação do pagamento.

Quais chaves usar?

Dado	Onde usar	Recomendação
`api_key` do Gateway	Seu servidor	Nunca expor no HTML, JavaScript público ou aplicativos clientes.
`smart_form.public_key`	Página de pagamento	É a chave pública recebida ao criar a Venda e utilizada pelo SDK PayZen.
`smart_form.token`	Renderização do formulário	Valor temporário associado ao fluxo; use apenas enquanto válido e não exponha em logs desnecessários.
`uuid` da Venda	Seu backend e consultas autorizadas	Guarde para conferir o resultado e relacionar a transação ao pedido.

Fluxo recomendado

Crie a Venda no servidor com POST /v1/charges.
Confira o retorno do objeto smart_form e apresente o formulário com os recursos PayZen originais.
Configure um webhook de Venda Cyclopay em seu ambiente para receber atualizações.
Consulte o estado atual da Venda/Transação pela API quando precisar reconciliar o resultado.
Atualize o pedido apenas após confirmação financeira adequada ao seu caso.

Webhook da PayZen e webhook da Cyclopay

A comunicação interna PayZen → Gateway utiliza um endpoint do próprio Orquestrador. Ele não deve ser usado como o endpoint de notificação da sua aplicação.

O webhook configurado por você no Gateway Cyclopay é o canal indicado para receber mudanças na Venda. A entrega pode ser repetida; seu receptor deve suportar notificações duplicadas e consultar dados atuais em caso de dúvida.

📘
Redirecionamento não confirma o pagamento
A página definida em kr-post-url-success pode informar que o pagamento está sendo conferido. Ela não substitui o recebimento do webhook ou a consulta autorizada à API.

Expiração e nova tentativa

Um form token inválido/expirado requer um novo fluxo controlado pelo servidor. Antes de criar uma nova Venda, verifique o estado da anterior para evitar cobranças ou pedidos duplicados. Não documentamos um prazo rígido de validade, pois ele não foi confirmado universalmente nesta revisão.

Mais informações

Configurar Webhooks · Consultar uma Venda · Resultado e Comprovante.