Para utilizar os postbacks, é necessário aprender o que fazer e como fazê-lo. No próximos passos aprenderemos:
Como utilizar;
Formato do postback;
Como validar o postback;
Como verificar os postbacks;
Como reenviar um postback.
## 1. Usando os postbacks
Os postbacks podem ser configurados no momento da criação de transações (transactions) e de assinaturas (subscriptions) através do parâmetro `postback_url` como mostra os exemplos abaixo:
Veja o postback em assinaturas:
Postback em localhost?
Para realizar testes, é possível utilizar o site [requestBin](🔗) para gerar uma URL temporária e analisar os postbacks enviados ou o programa [ngrok](🔗) para gerar e vincular uma URL temporária ao IP da máquina de teste / desenvolvimento. Essa URL pode ser utilizada no parâmetro _postback_url_.
Temporal
Partindo do primeiro postback, os próximos são enviados com o seguinte padrão de intervalo de tempo, em minutos: 1 (três vezes), 5 (três vezes), 60 (25 vezes)
Postback de transações de assinaturas
Você pode configurar em sua Dashboard se gostaria de receber postbacks quando uma transação pertencente a uma assinatura acaba de ser criada.
## 2. Formato dos postbacks
Quando a `postback_url` é passada, a transação é retornada com status `processing`, e as mudanças de status são enviadas para o seu servidor na URL de postback. Isso é feito através de um request `HTTP POST` com os seguintes parâmetros:
| Parâmetro | Descrição | Observação |
| id | id da transação | |
| event | A qual evento o postback se refere. | Transações: `transaction_status_changed`.
Assinatura: `subscription_status_changed`
Link de Pagamento:
`order_status_changed`
Recebedor:
`recipient_status_changed` |
| old_status | Status anterior da transação | |
| desired_status | Status ideal para objetos deste tipo, em um fluxo normal, onde autorização e captura são feitos com sucesso, por exemplo. | |
| current_status | Status para o qual efetivamente mudou | |
| object | Qual o tipo do objeto referido. | Transações: `transaction`
Assinaturas: `subscription`
Link de Pagamento: `order`
Recebedor: `recipient` |
| transaction | Possui todas as informações do objeto. Para acessar objetos internos basta acessar a chave transaction[objeto1][objeto2]. **Ex**: para acessar o ddd: transaction[phone][ddd] | |
Payload
Para ver os exemplos de Payload, clique [aqui](🔗) para ver em nossa página de referência
Current transaction
Retorna a última transação relacionada à respectiva subscription. Para cartão de crédito, retorna a última cobrança feita, e para boleto, retorna o último boleto gerado.
Formato
Diferentemente das respostas da API Pagar.me, o postback sempre terá seus parâmetros em `
application/x-www-form-urlencoded`
## 3. Como validar um postback
A validação do postback serve para verificar se realmente ele foi enviado pela Pagar.me, e é de extrema importância a sua utilização para que suas transações estejam seguras.
Para fazer a validação, são necessárias duas informações de nosso postback:
Valor do header 'X-Hub-Signature'. Vamos chamar esse valor de "assinatura do postback";
Corpo da requisição (no mesmo formato mostrado na seção anterior).
Com esses dois valores, basta realizar o [HMAC-SHA1](🔗) do corpo da requisição utilizando a sua API Key e comparar com a assinatura do postback. Se os valores forem iguais, excelente. Caso contrário, não fomos nós que enviamos essa requisição!
## 4. Verificando os postbacks
Após um postback ser enviado, existem duas situações que podem ocorrer:
Recebemos um retorno com status code 2xx do postback;
Ocorre algum erro no recebimento do postback e recebemos um status code diferente de 2xx (ou até não recebemos uma resposta).
No primeiro caso, nada mais ocorre. Já no segundo caso, começaremos então a fazer tentativas de reenvio do postback. Por padrão, são feitas até 31 novas tentativas.
Se existir algo estranho com sua integração com os nossos postbacks, você consegue monitorar isso do lado da sua aplicação:
Na lista de postbacks é possível visualizar as informações essenciais do postback enviado:
Dessas informações, os mais importantes são:
deliveries: lista da tentativas de (re)envio do postback relacionado;
response_body: qual foi a resposta de sua aplicação ao postback.
## 5. Reenvio de postbacks
Se necessário, há uma rota que força o reenvio de um postback. Isso para casos em que não foi possível completar o processo, ou por quaisquer outros motivos ligados à sua aplicação.
Vale ressaltar
A chamada à rota de reenvio implica na pausa de possíveis reenvios futuros. Ou seja, se for feito um reenvio antes da 31a tentativa, não completaremos as 31 retentativas.