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 PagBank que inicia o processo de notificação ao enviar um código para seu sistema.

Configurando o recebimento de notificações##

Para utilizar a API de Notificações você deve primeiramente informar o endereço (URL) do seu sistema para o qual o PagBank enviará os códigos de notificação. Isso pode ser feito na página de configurações do PagBank.

Você também pode passar a URL de notificação dinamicamente na maioria das APIs do PagBank, utilizando o parâmetro notificationURL.

Recebendo uma notificação de transação##

Uma vez configurado o endereço para onde o PagBank irá enviar notificações, o próximo passo é preparar seu sistema para receber, nesse endereço, um código de notificação.

O PagBankenvia as notificações para a URL que você configurou usando o protocolo HTTP, pelo método POST.

Observação: Não há uma ordem específica de envio dos campos notificationCode e notificationType; eles podem ser alternados.

Veja abaixo um exemplo de notificação enviada pelo PagBank (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.

Enquanto seu sistema não receber uma notificação, o PagBank 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 PagBank, isto é, garantir que todas as transações recebidas por você no PagBank 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.

Consultando uma notificação de 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.

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>
    <liquidation>
       <contractType>FULL</contractType>
       <contractDescription>Tipo de contrato quando a liquidação ocorre internamente</contractDescription>
    </liquidation>
</transaction>

Abaixo são descritos os campos do XML de resposta da consulta a uma notificação de transação.

Status da transação

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 PagBank e as possíveis transições entre eles.