These docs are for v1.0. Click to read the latest docs for v4.1.

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.

1598

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.

PARÂMETRODESCRIÇÃO
notificationCodeO 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.
Formato: Uma sequência de 39 caracteres.
notificationTypeO tipo da notificação enviada.

Tipo: Texto.
Formato: Para as notificações de transações o valor deste campo será "transaction".

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.

PARÂMETRODESCRIÇÃO
Código da Notificação (após notifications/)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.
Tipo: Texto.
Formato: Uma sequência de 39 caracteres.

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.

CAMPODESCRIÇÃO
xml <transaction> <date> Data da criação da transação. Informa o momento em que a transação foi criada.
Presença: Obrigatória.
Tipo: Data/hora.
Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatação de datas.
xml <transaction> <lastEventDate> Data do último evento. Informa o momento em que ocorreu a última alteração no status da transação.
Presença: Obrigatória.
Tipo: Data/hora.
Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatação de datas.
xml <transaction> <code> Código identificador da transação. Retorna o código que identifica a transação de forma única.
Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de 36 caracteres.
xml <transaction> <reference> 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 PagBank às vendas registradas no seu sistema.
Presença: Opcional.
Tipo: Texto.
Formato: Livre, com o limite de 200 caracteres.
xml <transaction> <type> 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.

1- Pagamento: a transação foi criada por um comprador fazendo um pagamento.
Este é o tipo mais comum de transação que você irá receber.

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.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <status> 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
xml <transaction> <cancellationSource> Origem do cancelamento. Informa a origem do cancelamento da transação: pelas instituições financeiras (Banco Emissor ou Operadora do Cartão) ou pelo PagBank.
Valor Significado
INTERNAL PagBank
EXTERNAL Instituições Financeiras
Presença: Opcional (somente quando transactionStatus igual a 7).
Tipo: Texto.
Formato: Valores possíveis INTERNAL ou EXTERNAL.
xml <transaction> <paymentMethod> <type> 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.


CodigoSignificado
1Cartão de crédito: o comprador escolheu pagar a transação com cartão de crédito.
2Boleto: o comprador optou por pagar com um boleto bancário.
3Débito online (TEF): o comprador optou por pagar a transação com débito online de algum dos bancos conveniados.
4Saldo PagBank: o comprador optou por pagar a transação utilizando o saldo de sua conta PagBank.
5 Oi Paggo *: o comprador escolheu pagar sua transação através de seu celular Oi.
7 Depósito em conta: o comprador optou por fazer um depósito na conta corrente do PagBank. Ele precisará ir até uma agência bancária, fazer o depósito, guardar o comprovante e retornar ao PagBank para informar os dados do pagamento. A transação será confirmada somente após a finalização deste processo, que pode levar de 2 a 13 dias úteis.
8Cartão Emergencial Caixa (Débito): disponível apenas nos checkouts com interface do PagBank (redirect e lightbox).
11 PIX: o comprador escolheu pagar a transação utilizando o PIX.


* Os tipos marcados não estão disponíveis para utilização.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <paymentLink> 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.
Presença: Somente para pagamentos via Boleto e TEF.
Tipo: Texto.
Formato: URL
xml <transaction> <paymentMethod> <code> 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.

CodigoSignificado
101Cartão de crédito Visa.
102Cartão de crédito MasterCard.
103Cartão de crédito American Express.
104Cartão de crédito Diners.
105Cartão de crédito Hipercard.
106 Cartão de crédito Aura.
107Cartão de crédito Elo.
108Cartão de crédito PLENOCard.
109Cartão de crédito PersonalCard.
110Cartão de crédito JCB.
111Cartão de crédito Discover.
112Cartão de crédito BrasilCard.
113Cartão de crédito FORTBRASIL.
114Cartão de crédito CARDBAN.
115Cartão de crédito VALECARD.
116Cartão de crédito Cabal.
117Cartão de crédito Mais!.
118Cartão de crédito Avista.
119Cartão de crédito GRANDCARD.
120Cartão de crédito Sorocred.
122Cartão de crédito Up Policard.
123Cartão de crédito Banese Card.
201Boleto Bradesco.
202Boleto Santander.
301Débito online Bradesco.
302Débito online Itaú.
303Débito online Unibanco.
304Débito online Banco do Brasil.
305Débito online Banco Real.
306Débito online Banrisul.
307Débito online HSBC.
401Saldo PagSeguro.
402PIX.
501Oi Paggo. _
701Depósito em conta - Banco do Brasil


_ Os meios de pagamento marcados não estão disponíveis para utilização.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <grossAmount> 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.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.
xml <transaction> <discountAmount> 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.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.
xml <transaction> <feeAmount> Valor total das taxas cobradas. Informa o valor total das taxas cobradas pelo PagBank nesta transação.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.
xml <transaction> <netAmount> 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.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.
xml <transaction> <escrowEndDate> Data de crédito. Data em que o valor da transação estará disponível na conta do vendedor.
Presença: Presente apenas quando o status da transação for um dos seguintes valores:
Paga (3), Disponível (4), Em disputa (5) ou Devolvida (6).
Tipo: Data/hora.
Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatação de datas.
xml <transaction> <extraAmount> 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.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto (“.”). Por exemplo, 1234.56 ou -1234.56.
xml <transaction> <installmentCount> Número de parcelas. Indica o número de parcelas que o comprador escolheu no pagamento com cartão de crédito.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <itemCount> Número de itens da transação. Aponta o número de itens contidos nesta transação.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <items> <item> <id> 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.
Presença: Obrigatória.
Tipo: Texto.
Formato: Livre.
xml <transaction> <items> <item> <description> 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.
Presença: Obrigatória.
Tipo: Texto.
Formato: Livre.
xml <transaction> <items> <item> <amount> 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.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56).
xml <transaction> <items> <item> <quantity> Quantidade do item. Informa a quantidade do item da transação. Está é a quantidade que foi especificada no fluxo de pagamento.
Presença: Obrigatória.
Tipo: Número.
Formato: Um número inteiro maior ou igual a 1 e menor ou igual a 999.
xml <transaction> <sender> <email> E-mail do comprador. Informa o e-mail do comprador que realizou a transação.
Presença: Obrigatória.
Tipo: Texto.
Formato: um e-mail válido (p.e., [email protected]), com no máximo 60 caracteres.
xml <transaction> <sender> <name> Nome completo do comprador. Informa o nome completo do comprador que realizou o pagamento.
Presença: Opcional.
Tipo: Texto.
Formato: No mínimo duas sequências de caracteres, com o limite total de 50 caracteres.
xml <transaction> <sender> <phone> <areaCode> DDD do comprador. Informa o código de área (DDD) do comprador que realizou o pagamento.
Presença: Opcional.
Tipo: Número.
Formato: Um número de 2 dígitos correspondente a um DDD válido.
xml <transaction> <sender> <phone> <number> Número de telefone do comprador. Informa o número do telefone do comprador que realizou o pagamento.
Presença: Opcional.
Tipo: Número.
Formato: Um número de 7 a 9 dígitos.
xml <transaction> <shipping> <type> 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.
CodigoSignificado
1Encomenda normal (PAC).
2SEDEX.
3Tipo de frete não especificado.


Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
xml <transaction> <shipping> <cost> Custo total do frete. Informa o custo total do frete, a partir das opções de frete informadas no fluxo de pagamento.
Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56).
xml <transaction> <shipping> <address> <country> País do endereço de envio. Informa o país do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: No momento, apenas o valor BRA é permitido.
xml <transaction> <shipping> <address> <state> Estado do endereço de envio. Informa o estado do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: Duas letras, representando a sigla do estado brasileiro correspondente.
xml <transaction> <shipping> <address> <city> Cidade do endereço de envio. Informa a cidade do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: Livre. Deve ser um nome válido de cidade do Brasil, de acordo com os dados dos Correios.
xml <transaction> <shipping> <address> <postalCode> CEP do endereço de envio. Informa o CEP do endereço de envio do produto.
Presença: Opcional.
Tipo: Número.
Formato: Um número de 8 dígitos.
xml <transaction> <shipping> <address> <district> Bairro do endereço de envio. Informa o bairro do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: Livre.
xml <transaction> <shipping> <address> <street> Nome da rua do endereço de envio. Informa o nome da rua do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: Livre.
xml <transaction> <shipping> <address> <number> Número do endereço de envio. Informa o número do endereço de envio do produto.
Presença: Opcional.
Tipo: Texto.
Formato: Livre.
xml <transaction> <liquidation> <contractType>Tipo de contrato de liquidação. Informa o tipo de contrato de liquidação para a transação informada.
Presença: Opcional.
Tipo: Texto.
Formato: Só aceita valores "FULL" ou "VAN"
xml <transaction> <liquidation> <contractDescription>Descrição do tipo de contrato de liquidação. Informa a descrição do tipo de contrato de liquidação para a transação informada.
Presença: Opcional.
Tipo: Texto.
Formato: Livre.

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.

CÓDIGOSTATUSDESCRIÇÃO
1Aguardando pagamentoO comprador iniciou a transação, mas até o momento o PagBanknão recebeu nenhuma informação sobre o pagamento. Quando a resposta da instituição financeira é muito rápida, omitimos esta notificação.

Transições:
Para Paga: Quando a operação é confirmada pela instituição financeira.
Para Em análise: Quando a operação entra em uma fila para que sejam feitas análises adicionais pela equipe do PagBank.
Para Cancelada: Quando a operação é negada pela instituição financeira ou quando o PagBank não recebe uma confirmação após um intervalo de tempo.
2Em análiseO comprador optou por pagar com um cartão de crédito e o PagBank está analisando o risco da transação.

Transições:
Para Paga: Quando tanto o PagBank quanto a operadora de cartões de crédito aprovam a transação.
Para Cancelada: Quando o PagBank ou a operadora de cartões de crédito negam a transação.
3PagaA transação foi paga pelo comprador e o PagBank 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 PagBank pode esperar o fim do prazo de liberação da transação.

Transições:
Para Em disputa: Quando o comprador, dentro do prazo de liberação da transação, indicar que não recebeu o produto ou serviço adquirido, ou que o mesmo foi entregue com problemas. Este processo é chamado de disputa e é mediado pela equipe do PagBank. Para saber mais, veja a página de explicação sobre disputas.
Para Devolvida: Quando você entrar em acordo com o comprador para devolver o valor da transação, pois não possui mais o produto em estoque ou não pode mais prestar o serviço contratado.
Para Disponível: Quando a transação chega ao final de seu prazo de liberação sem ter sido retornada e não há nenhuma disputa aberta.
4DisponívelA 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:
Para Devolvida: Quando você entrar em acordo com o comprador para devolver o valor da transação, pois não possui mais o produto em estoque ou não pode mais prestar o serviço contratado.
Para Em disputa: Quando o comprador indicar que não recebeu o produto ou serviço adquirido, ou que o mesmo foi entregue com problemas. Este processo é chamado de disputa e é mediado pela equipe do PagBank. Para saber mais, veja a página de explicação sobre disputas. Uma transação pode entrar em disputa, mesmo após a finalização do prazo de liberação do pagamento.
5Em disputaO 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 PagBank. A equipe do PagBanko é 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:
Para Disponível: Quando a disputa é resolvida em favor do vendedor, indicando que o produto ou serviço foi efetivamente entregue corretamente.
Para Devolvida: Quando a disputa é resolvida em favor do comprador, indicando que o produto não foi entregue ou foi entregue fora das especificações e deve ser devolvido.
Para Paga: Quando a disputa é resolvida em favor do vendedor, porém antes da finalização do prazo de liberação do pagamento.
6DevolvidaO *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 PagBank, pois não são nem um crédito e nem um débito.

Transições:
Nenhuma.
7CanceladaA 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 PagBank ou pela operadora.

Transições:
Nenhuma.
8DebitadoA valor da transação foi devolvido para o comprador.

Transições:
Nenhuma.
9Retenção temporáriaO comprador abriu uma solicitação de chargeback junto à operadora do cartão de crédito.

Transições: