Notificações
O que você vai encontrar aqui:
Configurando o recebimento de transações
Recebendo uma notificação de transação
Consultando uma notificação de transação
Status da transação
O serviço de notificações de transações permite que sua aplicação seja avisada automaticamente sempre que ocorrer uma mudança no status de alguma transação destinada a sua conta. Com isso, alcançando uma maior automação de seus processos de venda, principalmente quando o seu volume de transações aumenta e fica cada vez mais importante eliminar etapas manuais em seus processos.
A figura abaixo ilustra o funcionamento da API de Notificações. Note que é o PagSeguro que inicia o processo de notificação ao enviar um código para seu sistema.


Para utilizar a API de Notificações você deve primeiramente informar o endereço (URL) do seu sistema para o qual o PagSeguro enviará os códigos de notificação. Isso pode ser feito na página de configurações do PagSeguro.
Você também pode passar a URL de notificação dinamicamente na maioria das APIs do PagSeguro, utilizando o parâmetro notificationURL
.
Uma vez configurado o endereço para onde o PagSeguro irá enviar notificações, o próximo passo é preparar seu sistema para receber, nesse endereço, um código de notificação.
O PagSeguro envia as notificações para a URL que você configurou usando o protocolo HTTP, pelo método POST.
Veja abaixo um exemplo de notificação enviada pelo PagSeguro (as linhas foram quebradas para facilitar a leitura):
POST http://lojamodelo.com.br/notificacao HTTP/1.1
Host:pagseguro.uol.com.br
Content-Length:85
Content-Type:application/x-www-form-urlencoded
notificationCode=766B9C-AD4B044B04DA-77742F5FA653-E1AB24
notificationType=transaction
A tabela abaixo descreve os parâmetros enviados na notificação.
PARÂMETRO | DESCRIÇÃO |
---|---|
| O código que identifica a notificação. Este código deve ser usado para consultar a notificação e obter os dados da transação associada. Note que o código que identifica a notificação não é o mesmo que o código que identifica a transação. Tipo: Texto. |
| O tipo da notificação enviada. Tipo: Texto. |
Enquanto seu sistema não receber uma notificação, o PagSeguro irá envia-la novamente a cada 2 horas, até um máximo de 5 tentativas. Se seu sistema ficou indisponível por um período maior que este e não recebeu nenhum dos envios da notificação, ainda assim é possível obter os dados de suas transações usando a Consulta de Transações. É uma boa prática realizar uma consulta periódica a esta API para conciliar o seu sistema com o PagSeguro, isto é, garantir que todas as transações recebidas por você no PagSeguro foram identificadas pelo seu sistema.
Note que a notificação não possui nenhuma informação sobre a transação. Portanto, assim que seu sistema recebe uma notificação, ele deve consultá-la para obter os dados da transação.
Para consultar uma notificação de transação, você deve fazer uma requisição à API de Consulta de Notificações, informando o código da notificação. O exemplo abaixo ilustra uma chamada à essa API:
GET https://ws.pagseguro.uol.com.br/v3/transactions/notifications/{{codigo-notificacao}}?{{credenciais}}
A autenticação desta solução pode ser feita com credenciais de conta ou credenciais de aplicação.
Abaixo são descritos os parâmetros usados na consulta a uma notificação.
PARÂMETRO | DESCRIÇÃO |
---|---|
| Código identificador da notificação. Informa o código da notificação que você quer consultar. O código deve ser informado no caminho da URL. Você deve usar o código que recebeu pelo parâmetro notificationCode no envio da notificação. Presença: Obrigatória. |
A resposta da consulta a uma notificação é dada em formato XML, como no exemplo abaixo:
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transaction>
<date>2011-02-10T16:13:41.000-03:00</date>
<code>9E884542-81B3-4419-9A75-BCC6FB495EF1</code>
<reference>REF1234</reference>
<type>1</type>
<status>3</status>
<paymentMethod>
<type>2</type>
<code>202</code>
</paymentMethod>
<grossAmount>300021.45</grossAmount>
<discountAmount>0.00</discountAmount>
<creditorFees>
<intermediationRateAmount>0.40</intermediationRateAmount>
<intermediationFeeAmount>11970.86</intermediationFeeAmount>
</creditorFees>
<netAmount>288050.19</netAmount>
<extraAmount>0.00</extraAmount>
<installmentCount>1</installmentCount>
<itemCount>3</itemCount>
<items>
<item>
<id>0001</id>
<description>Produto PagSeguroI</description>
<quantity>1</quantity>
<amount>99999.99</amount>
</item>
<item>
<id>0002</id>
<description>Produto PagSeguroII</description>
<quantity>2</quantity>
<amount>99999.98</amount>
</item>
</items>
<sender>
<name>José Comprador</name>
<email>[email protected]</email>
<phone>
<areaCode>99</areaCode>
<number>99999999</number>
</phone>
</sender>
<shipping>
<address>
<street>Av. PagSeguro</street>
<number>9999</number>
<complement>99o andar</complement>
<district>Jardim Internet</district>
<postalCode>99999999</postalCode>
<city>Cidade Exemplo</city>
<state>SP</state>
<country>ATA</country>
</address>
<type>1</type>
<cost>21.50</cost>
</shipping>
</transaction>
Abaixo são descritos os campos do XML de resposta da consulta a uma notificação de transação.
CAMPO | DESCRIÇÃO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Data da criação da transação. Informa o momento em que a transação foi criada. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Data do último evento. Informa o momento em que ocorreu a última alteração no status da transação. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Código identificador da transação. Retorna o código que identifica a transação de forma única. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Código de referência da transação. Informa o código que foi usado para fazer referência ao pagamento. Este código foi fornecido no momento do pagamento e é útil para vincular as transações do PagSeguro às vendas registradas no seu sistema. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tipo da transação. Representa o tipo da transação recebida. Os valores mais comuns para este campo e seus respectivos resultados são descritos abaixo. Outros tipos menos comuns de transações foram omitidos. Note que novos tipos podem ser adicionados em versões futuras da API. Presença: Obrigatória. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Status da transação. Informa o código representando o status da transação, permitindo que você decida se deve liberar ou não os produtos ou serviços adquiridos. Os valores possíveis estão descritos no diagrama de status de transações e são apresentados juntamente com seus respectivos códigos na tabela de Status da transação | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Origem do cancelamento. Informa a origem do cancelamento da transação: pelas instituições financeiras (Banco Emissor ou Operadora do Cartão) ou pelo PagSeguro. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tipo do meio de pagamento. Informa o tipo do meio de pagamento usado pelo comprador. Este tipo agrupa diversos meios de pagamento e determina de forma geral o comportamento da transação. A tabela abaixo descreve os valores disponíveis e seus significados.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Link para o Pagamento. Informa a URL para a exibição do boleto ou, quando o meio de pagamento for TEF, a URL para abrir o pop-up do banco. Quando o meio de pagamento for Cartão de crédito este parâmetro será omitido. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Código identificador do meio de pagamento. Informa um código que identifica o meio de pagamento usado pelo comprador. O meio de pagamento descreve a bandeira de cartão de crédito utilizada ou banco escolhido para um débito online. A tabela abaixo descreve os possíveis valores e seus significados.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor bruto da transação. Informa o valor bruto da transação, calculado pela soma dos preços de todos os itens presentes no pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor do desconto dado. Informa o valor do desconto dado a compradores que optaram por pagar com débito online ou boleto. Este desconto aplica-se quando você opta por incluir no preço dos produtos o custo do parcelamento de pagamentos com cartão de crédito. O desconto é dado para não onerar os compradores que optaram por meios à vista. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor total das taxas cobradas. Informa o valor total das taxas cobradas pelo PagSeguro nesta transação. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor líquido da transação. Informa o valor líquido da transação, que corresponde ao valor bruto, menos o valor das taxas. Caso presente, o valor de extraAmount (que pode ser positivo ou negativo) também é considerado no cálculo. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Data de crédito. Data em que o valor da transação estará disponível na conta do vendedor. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor extra. Informa um valor extra que foi somado ou subtraído do valor pago pelo comprador. Este valor é especificado por você no pagamento e pode representar um valor que você quer cobrar separadamente do comprador ou um desconto que quer dar a ele. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Número de parcelas. Indica o número de parcelas que o comprador escolheu no pagamento com cartão de crédito. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Número de itens da transação. Aponta o número de itens contidos nesta transação. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Identificador do item. Identifica o item da transação. Este identificador deve ser único por transação e foi informado por você no fluxo de pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Descrição do item. Descreve o item da transação. A descrição é um texto explicativo do item que você especificou no fluxo de pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Valor unitário do item. Informa o preço unitário do item da transação. Este é o valor que foi especificado no fluxo de pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Quantidade do item. Informa a quantidade do item da transação. Está é a quantidade que foi especificada no fluxo de pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| E-mail do comprador. Informa o e-mail do comprador que realizou a transação. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Nome completo do comprador. Informa o nome completo do comprador que realizou o pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DDD do comprador. Informa o código de área (DDD) do comprador que realizou o pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Número de telefone do comprador. Informa o número do telefone do comprador que realizou o pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tipo de frete. Informa o tipo de frete a ser usado para o envio do produto. A tabela abaixo informa os valores possíveis e seus significados.
Presença: Obrigatória. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Custo total do frete. Informa o custo total do frete, a partir das opções de frete informadas no fluxo de pagamento. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| País do endereço de envio. Informa o país do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado do endereço de envio. Informa o estado do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Cidade do endereço de envio. Informa a cidade do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| CEP do endereço de envio. Informa o CEP do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Bairro do endereço de envio. Informa o bairro do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Nome da rua do endereço de envio. Informa o nome da rua do endereço de envio do produto. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Número do endereço de envio. Informa o número do endereço de envio do produto. |
O status da transação indica o estágio atual da transação e determina que ações você deve tomar em relação a ela. Por exemplo, o status pode indicar que a transação está paga, o que significa que você pode liberar o produto para o comprador. Por outro lado, se o status indica que a transação ainda está em análise, ela ainda não foi aprovada e pode ser cancelada.
Vale lembrar que algumas transações passam por diferentes status em um período de tempo muito curto. Por exemplo, transações de cartão de crédito, que podem passar pelo status aguardando pagamento e paga praticamente no mesmo instante. Em situações como essa, uma única notificação é enviada ao seu sistema.
A figura abaixo mostra uma máquina de estados que descreve os status de transação do PagSeguro e as possíveis transições entre eles.


CÓDIGO | STATUS | DESCRIÇÃO |
---|---|---|
1 | Aguardando pagamento | O comprador iniciou a transação, mas até o momento o PagSeguro não recebeu nenhuma informação sobre o pagamento. Quando a resposta da instituição financeira é muito rápida, omitimos esta notificação. Transições: |
2 | Em análise | O comprador optou por pagar com um cartão de crédito e o PagSeguro está analisando o risco da transação. Transições: |
3 | Paga | A transação foi paga pelo comprador e o PagSeguro já recebeu uma confirmação da instituição financeira responsável pelo processamento. Quando uma transação tem seu status alterado para Paga, isso significa que você já pode liberar o produto vendido ou prestar o serviço contratado. Porém, note que o valor da transação pode ainda não estar disponível para retirada de sua conta, pois o PagSeguro pode esperar o fim do prazo de liberação da transação. Transições: |
4 | Disponível | A transação foi paga e chegou ao final de seu prazo de liberação sem ter sido retornada e sem que haja nenhuma disputa aberta. Este status indica que o valor da transação está disponível para saque. Transições: |
5 | Em disputa | O comprador, dentro do prazo de liberação da transação, abriu uma disputa. A disputa é um processo iniciado pelo comprador para indicar que não recebeu o produto ou serviço adquirido, ou que o mesmo foi entregue com problemas. Este é um mecanismo de segurança oferecido pelo PagSeguro. A equipe do PagSeguro é responsável por mediar a resolução de todas as disputas, quando solicitado pelo comprador. Para mais informações, veja a página de explicação sobre disputas. Transições: |
6 | Devolvida | O *valor da transação foi devolvido para o comprador. Se você não possui mais o produto vendido em estoque, ou não pode por alguma razão prestar o serviço contratado, você pode devolver o valor da transação para o comprador. Esta também é a ação tomada quando uma disputa é resolvida em favor do comprador. Transações neste status não afetam o seu saldo no PagSeguro, pois não são nem um crédito e nem um débito. Transições: |
7 | Cancelada | A transação foi cancelada sem ter sido finalizada. Quando o comprador opta por pagar com débito online ou boleto bancário e não finaliza o pagamento, a transação assume este status. Isso também ocorre quando o comprador escolhe pagar com um cartão de crédito e o pagamento não é aprovado pelo PagSeguro ou pela operadora. Transições: |
8 | Debitado | A valor da transação foi devolvido para o comprador. Transições: |
9 | Retenção temporária | O comprador abriu uma solicitação de chargeback junto à operadora do cartão de crédito. Transições: |
Updated over 1 year ago