Etapas e características das notificações da transação
O processo de notificação transacional ocorre em duas etapas, que são a notificação de finalização da transação e a notificação de mudança de status.
| ETAPA | TIPO DE URL* | DESCRIÇÃO | CONTEÚDO | FORMATO |
|---|---|---|---|---|
| Notificação de finalização da transação | URL de Notificação | É enviada após o comprador clicar em Finalizar, gerando a transação. Essa notificação é enviada apenas no momento que a transação é finalizada, independentemente se houve alteração do status, ou seja, não significa que a transação foi paga. | Contém todos os dados da venda. | POST ou JSON |
| Notificação de mudança de status | URL de Mudança de Status | É enviada quando há mudança de status na transação. O status pode ser alterado de “Pendente” para “Pago”, “Cancelada” ou “Não Finalizada”, entre outros. Veja a lista completa de status na tabela Status e códigos APIs. | Contém os dados de identificação do pedido (não tem os dados do carrinho). | POST |
*As notificações são enviadas para as URLs definidas pelo estabelecimento nas Configurações da Loja e contêm os dados das transações realizadas no Link de Pagamento.
Vale destacar que o Link de Pagamento realiza a notificação somente quando uma transação é considerada finalizada, ou seja, o comprador preencheu todos os dados da tela de pagamento e clicou em Finalizar.
Exemplo: O comprador acessa o link de pagamento e escolhe pagar via Pix. Ao clicar em Finalizar, o Link de Pagamento gera a chave Pix e envia para a loja a notificação de finalização da transação, que estará com o status “Pendente”. Quando o comprador fizer o pagamento via Pix, a transação ficará com o status “Pago” e o Link de Pagamento enviará a notificação de mudança de status.
Para receber notificações é necessário configurar o Certificado SSL
Além disso, não há implementação de autenticação para o envio de notificações, então, se o endpoint da loja possuir camadas de firewall, isso pode impedir o recebimento das notificações.
Características das notificações
As URLs para notificação são webhooks que podem receber uma notificação via POST ou via JSON:
| TIPO | DESCRIÇÃO |
|---|---|
| POST | Notificação onde a loja é passiva. |
| JSON | Notificação onde a loja realiza uma consulta. |
O endereço deve ser HTTPS e não é permitido usar uma porta fora do padrão HTTPS (443).
Formato das notificações
Nas notificações suportadas pela API do Link de Pagamento o formato enviado é Form Data, discriminado pelo header Content-Type ‘x-www-form-urlencoded’.
A Cielo pode demorar até no máximo três minutos para enviar as notificações.
Retorno esperado
- O servidor da loja deve enviar o retorno
HTTPStatus = 200 (OK)para a API do Link de Pagamento, indicando que a notificação foi recebida e processada com sucesso; - Essa resposta do servidor da loja deve ser enviada em até 100 segundos. Se o nosso sistema não receber nenhuma resposta nesse tempo, irá cancelar o envio da notificação e tentar novamente após uma hora.
Erro no envio da notificação
Se a URL cadastrada retornar algum erro ou estiver indisponível, serão realizadas três novas tentativas, com intervalo de uma hora entre cada POST.
Quando um erro é retornado, enviamos um e-mail informando a falha na tentativa de envio da notificação:
Ao receber esse e-mail, recomendamos que verifique a configuração da URL e confira se as URLs cadastradas estão corretas.
Caso a notificação não seja recebida, é possível solicitar o reenvio manualmente nos Detalhes do pedido, clicando no ícone da seta.