Generalidades sobre a IPN
Esse documento define o conceito de IPN e explica quando ela deve ser utilizada.
O que é uma IPN?
IPN é a abreviação de um termo inglês que significa Instant Payment Notification. Em português, chama-se de Notificação Instantânea de Pagamento:.
Uma IPN é uma notificação de servidor para servidor (servidor da plataforma de pagamento para o servidor do Estabelecimento Comercial) que permite ao site de e-commerce receber notificações em tempo real e automáticas quando ocorre um evento, por exemplo quando uma transação foi registrada.
Pode-se configurar o envio nos casos seguintes:
- evento ocorrendo no formulário de pagamento (formulário HTTPS): registro de um pagamento simples e recorrente, pagamento abandonado, etc.
- Operação procedente do
Back Office EC : registro de um pagamento simples ou recorrente, cancelamento, reembolso, modificação, validação de uma transação, etc.
Para receber as notificações, o Estabelecimento Comercial deve configurar pelo menos a regra de notificação de fim de pagamento. Esta regra é definida automaticamente na criação da loja.
Nenhuma IPN é enviada quando as trocas entre o Estabelecimento Comercial e a plataforma de pagamento ocorrem via Web Services (servidor para servidor) já que neste caso, o Estabelecimento Comercial analisa a resposta do Web Service que ele recebe em tempo real.
Esta notificação chama uma URL localizada no servidor do Estabelecimento Comercial. Esta URL chamada URL de notificação instantânea é definida pelo Estabelecimento Comercial no seu
O Estabelecimento Comercial pode definir diversas regras em função do tipo de evento.
Os dados são enviados em modo POST e dentre eles, encontra-se:
- O meio de pagamento usado pelo comprador,
- O código retorno de autorização,
- O tipo de autorização (pré-auto ou full),
- O detalhe do meio de pagamento usado pelo comprador (exemplo: tipo, número de cartão oculto, data de vencimento, etc.).
- O valor,
- O endereço e-mail do comprador,
- O número de pedido,
- Etc.
Os dados enviados na IPN são recebidos e analisados por um script desenvolvido pelo Estabelecimento Comercial no seu servidor. A execução deste script permitirá também ao Estabelecimento Comercial atualizar seu sistema de informação em função das informações recebidas.
A URL de notificação instantânea pode também ser sobrescrita na solicitação.
Como funciona uma IPN?
O diálogo entre o servidor do Estabelecimento Comercial e a plataforma de pagamento realiza-se via uma troca de dados. Para garantir a segurança das trocas, os dados são assinados com uma chave somente conhecida pelo Estabelecimento Comercial e pela plataforma de pagamento.
Para criar um pagamento, estes dados são enviados em um formulário HTML via o navegador do comprador (etapa 1).
No final do pagamento, o resultado será enviado ao site de e-commerce de duas maneiras:
- automaticamente via notificações enviadas à URL de notificação instantânea (etapa 2).
- pelo navegador quando o comprador clica no botão para voltar ao site de e-commerce (etapa3).
O tempo de processamento impacta diretamente o prazo para a visualização da página de resumo do pagamento. Quanto mais o processamento demorar, mais longo o tempo de espera antes de visualizar.
Qual é a diferença entre a URL de notificação instantânea e a URL de volta para a loja?
A gestão do diálogo com o site de e-commerce é realizada graças a dois tipos de URL:
- URL de notificação instantânea, usada para a IPN,
- URL para voltar para o site de e-commerce.
A URL de notificação instantânea permite à plataforma de pagamento notificar automaticamente o resultado do pagamento para o site de e-commerce. A URL de volta para o site de e-commerce é usada pelo navegador para redirecionar o comprador para voltar para o site de e-commerce quando ele clica no botão voltar para a loja.
Os dados enviados para o navegador são os mesmos que na IPN. O retorno para a loja deve permitir somente uma visualização do contexto ao comprador. Os dados recebidos não podem portanto ser usados para realizar o processamento de base de dados.
Como verificar se a IPN funciona?
No
O que fazer em caso de erro?
Se um problema ocorreu, o histórico das notificações permite obter várias informações:
- a hora da notificação (em tempo real no fim do pagamento),
- a duração de execução do script de análise na parte do servidor do Estabelecimento Comercial,
- os 100 primeiros símbolos que seu script escreve no canal aberto entre a plataforma de pagamento e o servidor do Estabelecimento Comercial (via recuperação dos printout neste canal).
No caso de um erro de execução da IPN, um e-mail de aviso é enviado para o endereço digitado no
Este e-mail contém:
- o código HTTP do erro encontrado,
- elementos de análise segundo o erro,
- os passos a seguir a partir do
Back Office EC para enviar de novo a notificação.
Pode-se também ativar uma opção de re-chamada automática da IPN (menu Configuração > Regras de notificações > aba Chamada URL de notificação > assinalar a caixa “Re-chamada automática em caso de falha”). C
Esta opção permite enviar de novo e automaticamente a notificação para o site de e-commerce após uma falha, até 4 vezes. As tentativas de chamadas são programadas a horários fixos a cada 15 minutos (00, 15, 30, 45). Após cada tentativa sem sucesso, um e-mail de aviso é enviado ao endereço e-mail como vimos antes. O e-mail enviado contém no seu título o número correspondente à tentativa de envio da notificação.
Diversos códigos de retorno de tipo HTTP podem ser exibidos durante as trocas entre servidores. Quando o código de retorno retornado começa por 4xx ou por 5xx, a re-chamada automática não se aplica.
Se o seu script cometer um erro, a plataforma de pagamento oferece-se para reproduzir manualmente o URL de notificação instantânea a partir da
Para resumir, aconselhamos respeitar estes 3 pontos:
- Fique atento com a configuração das suas regras de notificação,
- Teste a IPN,
- Leia os e-mails da plataforma de pagamento, eles são uteis mesmo.