Objeto-resposta Postback

❗️

Atenção: Essa versão de API será descontinuada

Essa versão da API Pagar.me já não é mais atualizada e, em breve, deixará de funcionar. Para que sua loja possa vender sem problemas, você precisa realizar sua integração usando a versão mais recente da nossa API, a V5.

No canto superior esquerdo da tela é indicado qual versão da documentação você está vendo. Clique na seta onde indica a versão e altere para a V5 para acessar a documentação.

Se você já é cliente, precisa realizar obrigatoriamente a migração para a versão V5.

Em caso de dúvidas, basta entrar em contato com o nosso time de atendimento através do e-mail, enviando a sua dúvida para [email protected] e por telefone, ligando para 4004-1330. Se você já é cliente pode também entrar em contato através do chat dentro da sua Dashboard.

Ao criar uma transação ou uma assinatura você tem a opção de passar o parâmetro postback_url na requisição. Essa é uma URL do seu sistema que irá então receber notificações a cada alteração de status dessas transações/assinaturas.

1. Propriedades de um postback

Propriedades específicas do postback:

PropriedadeDescrição
object
String
Nome do tipo do objeto criado/modificado.
Valor retornado: postback
status
String
Status atual do postback. Pode ser: processing, waiting_retry, pending_retry, failed, success
model
String
A que tipo de objeto o postback se relaciona. Pode ser 'transaction', 'subscription' ou 'recipient'
model_id
String
ID do objeto relacionado.
headers
String
String com formato json dos headers enviados no postback
payload
String
Corpo do postback, envolve o conteúdo do objeto a que corresponde a notificação. Dentre eles transaction, subscription e recipient. Mais na seção a seguir.
request_url
String
URL para a qual o postback foi enviado
retries
Integer
Quantidade de reenvios. A primeira tentativa não conta como uma retentativa
next_retry
Datetime
Data e hora do próximo reenvio.
deliveries
Array com objetos do tipo postback_delivery
Lista das tentativas até então. Retornam informações sobre a comunicação entre nossos servidores e sua aplicação, descrevendo status response header, etc.
date_created
Datetime
Data de criação
date_updated
Datetime
Data da ultima mudança
signature
String
Hmac SHA1 do payload
id
String
ID do postback

2. Payload de um postback

Você irá receber em sua postback_url, isto é, em seu servidor, uma propriedade chamada payload, em formato de query string. É ela que contém as informações do evento que ocorreu junto à transação ou assinatura de sua company. A seguir mais detalhes sobre cada propriedade:

PropriedadeDescrição
id
String
ID do objeto sendo enviado no payload. Objetos possíveis: transação, assinatura ou recebedor.
fingerprint
String
Hash gerada para validação do postback em seu servidor.
event
String
Define qual evento aconteceu para que o postback tenha sido enviado. Valores possíveis: transaction_status_changed, subscription_status_changed, recipient_status_changed, transaction_created.
old_status
String
Indica qual era o status antigo do objeto sendo enviado.
desired_status
String
Indica qual seria o status ideal para objetos deste tipo, em um fluxo normal.
current_status
String
Indica qual é o real status do objeto.
objectObjeto enviado e que teve mudanças significativas, para iniciar um postback. Valores possíveis: transaction, subscription ou recipient.

❗️

Eventuais novos status de transação

Novos status de transação podem ser criados e enviados dentro do payload do postback. Desta forma, a sua aplicação deve estar preparada para receber por postback status de transação que anteriormente não existiam.

3. Observações sobre postback

🚧

Atenção

Não é possível alterar a URL de postback de uma transaction, subscription ou recipient.

❗️

Problemas com postback?

Alguns pontos a considerar:

-Houve alguma mudança de url do seu sistema? Por exemplo : https://lojateste.com.br para https://novalojateste.com.br ; Se sim, você deve redirecionar os postbacks para sua nova url.

-Houve troca de protocolo? Por exemplo : http://lojateste.com.br para https://lojateste.com.br ; Este caso também requer que você mantenha ambas URLs funcionando, e redirecionando postback de acordo com necessidade. Caso tenha mais dúvidas, entre em contato com [email protected] para que possamos ajudar ;)

4. Postback deliveries

Cada tentativa de envio de postback cria uma nova entidade de delivery. Ou seja, um novo registro de tentativa, bem-sucedida ou não, de entrega de postback à sua aplicação. Segue a descrição de cada propriedade de um delivery:

PropriedadeDescrição
object
String
Nome do tipo do objeto criado/modificado.
Valor retornado: postback_delivery
status
String
Status do delivery. Pode ser: processing, failed, success
status_reason
String
Razão do status. Pode ser http_status_code ou null
status_code
String
Http status recebido como response de seus servidores.
response_time
Integer
Milissegundos entre envio do postback e a response
response_headers
String
Headers da response do postback
response_body
String
Corpo da resposta do postback. Esta é a response que seus servidores enviaram à API Pagar.me
date_created
Datetime
Data de criação do delivery
date_updated
Datetime
Data da última atualização do delivery
id
String
ID do delivery