Para utilizar os postbacks, é necessário aprender o que fazer e como fazê-lo. No próximos passos aprenderemos:

  1. Como utilizar;

  2. Formato do postback;

  3. Como validar o postback;

  4. Como verificar os postbacks;

  5. 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 mostram 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âmetroDescriçãoObservação
idID da transação.
eventA 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_statusStatus anterior da transação.
desired_statusStatus ideal para objetos deste tipo, em um fluxo normal, onde autorização e captura são feitos com sucesso, por exemplo.
current_statusStatus para o qual efetivamente mudou.
objectQual o tipo do objeto referido.Transações: `transaction` Assinaturas: `subscription` Link de Pagamento: `order` Recebedor: `recipient`
transactionPossui 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.