Consulta de Transações Por Intervalo de Datas

Visão Geral

Esta consulta permite obter as transações recebidas por você em um intervalo de datas. Ela pode ser usada periodicamente para verificar se o seu sistema recebeu todas as notificações de transações enviadas pelo PagSeguro, de forma a conciliar as transações armazenadas em seu sistema com o PagSeguro.

Consultas por Data

Legendas

Integração

Para consultar transações por intervalo de datas, você deve fazer uma requisição à API de Consulta de Transações, informando o intervalo desejado. O PagSeguro irá retornar todas as transações direcionadas para sua conta que foram criadas nesse intervalo. Veja abaixo um exemplo de chamada a essa API, que requer a utilização do protocolo HTTP e o método GET (as linhas foram quebradas para facilitar a leitura).

Observação Para utilizar a Sandbox PagSeguro para realizar a homologação da sua requisição, utilize o endpoint: https://ws.sandbox.pagseguro.uol.com.br/v2/transactions ao invés de https://ws.pagseguro.uol.com.br/v2/transactions

https://ws.pagseguro.uol.com.br/v2/transactions
?initialDate=2011-01-01T00:00
&finalDate=2011-01-28T00:00
&page=1
&maxPageResults=100
&email=suporte@lojamodelo.com.br
&token=95112EE828D94278BD394E91C4388F20

Parâmetros de Consulta

PARÂMETRO DESCRIÇÃO
initialDate Data inicial do intervalo.

Especifica a data inicial do intervalo de pesquisa. Somente transações criadas a partir desta data serão retornadas. Esta data não pode ser anterior a 6 meses da data corrente.

Presença: Obrigatória.
Tipo: Data/hora, com precisão de minutos.
Formato: YYYY-MM-DDThh:mm, o formato oficial do W3C para datas. Veja mais sobre formatação de datas.
finalDate Data final do intervalo.

Especifica a data final do intervalo de pesquisa.
A diferença entre initialDate e finalDate não pode ser superior a 30 dias.

Presença: Obrigatória.
Tipo: Data/hora, com precisão de minutos.
Formato: YYYY-MM-DDThh:mm, o formato oficial do W3C para datas. Veja mais sobre formatação de datas.
page página de resultados a ser retornada.

O Número de resultados retornado pela consulta por intervalo de datas pode ser grande, portanto é possível fazer a paginação dos resultados. A primeira página retornada é 1 e assim por diante. Este parâmetro especifica qual é a página de resultados a ser retornada.

Presença: Opcional. Se não especificada, a página 1 é retornada.
Tipo: Número.
Formato: Inteiro.
maxPageResults Número máximo de resultados por página.

Para limitar o tamanho da resposta de cada chamada à consulta, é possível especificar um número máximo de resultados por página. Este parâmetro permite especificar este limite.

Presença: Opcional. Se não especificada, serão retornados 50 resultados por página.
Tipo: Número.
Formato: Inteiro entre 1 e 1000.
email E-mail da conta que chama a API.

E-mail associado à conta PagSeguro que está realizando a chamada à API.

Presença: Obrigatória.
Tipo: Texto.
Formato: um e-mail válido (p.e., usuario@site.com.br), com no máximo 60 caracteres.
token Token da conta que chama a API.

Token correspondente á conta PagSeguro que está realizando a chamada à API. Para criar um token para sua conta PagSeguro, acesse a página de configurações de pagamentos.

Presença: Obrigatória.
Tipo: Texto.
Formato: uma sequência de 32 caracteres.

Exemplo de resposta

A resposta da consulta de transações por intervalo de datas é dada em formato XML. Nem todos os detalhes das transações são retornados por esta consulta; use a consulta de transações por código para obter mais detalhes, caso necessário. Veja uma resposta no exemplo abaixo.

<transactionSearchResult>  
    <date>2011-02-16T20:14:35.000-02:00</date>  
    <currentPage>1</currentPage>  
    <resultsInThisPage>10</resultsInThisPage>  
    <totalPages>1</totalPages>  
    <transactions>  
        <transaction>  
            <date>2011-02-05T15:46:12.000-02:00</date>  
            <lastEventDate>2011-02-15T17:39:14.000-03:00</lastEventDate>  
            <code>9E884542-81B3-4419-9A75-BCC6FB495EF1</code>  
            <reference>REF1234</reference>  
            <type>1</type>  
            <status>3</status>  
            <paymentMethod>  
                <type>1</type>  
            </paymentMethod>  
            <grossAmount>49900.00</grossAmount>  
            <discountAmount>0.00</discountAmount>  
            <feeAmount>0.00</feeAmount>  
            <netAmount>49900.00</netAmount>  
            <extraAmount>0.00</extraAmount>  
        </transaction>  
        <transaction>  
            <date>2011-02-07T18:57:52.000-02:00</date>  
            <lastEventDate>2011-02-14T21:37:24.000-03:00</lastEventDate>  
            <code>2FB07A22-68FF-4F83-A356-24153A0C05E1</code>  
            <reference>REF5678</reference>  
            <type>3</type>  
            <status>4</status>  
            <paymentMethod>  
                <type>3</type>  
            </paymentMethod>  
            <grossAmount>26900.00</grossAmount>  
            <discountAmount>0.00</discountAmount>  
            <feeAmount>0.00</feeAmount>  
            <netAmount>26900.00</netAmount>  
            <extraAmount>0.00</extraAmount>  
        </transaction>  
    </transactions>  
</transactionSearchResult>

Parâmetros de resposta

PARÂMETRO DESCRIÇÃO
<transactionSearchResult> Este campo é a raiz do XML de resposta e engloba os dados dos resultados da consulta.
<transactionSearchResult>
<date>
Data da consulta.

Informa o momento em que a consulta foi realizada.

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.
<transactionSearchResult>
<currentPage>
Índice da página atual.

Informa o índice da página de resultados sendo consultada. A primeira página de resultados é a de número 1 e assim por diante.

Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
<transactionSearchResult>
<resultsInThisPage>
Número de resultados na página atual.

Indica o número de resultados presentes na página atual.

Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
<transactionSearchResult>
<totalPages>
Número total de páginas.

Informa o número total de páginas no resultado da busca.

Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
<transactionSearchResult>
<transactions>
Representa as transações retornadas pela consulta.
<transactionSearchResult>
<transactions>
<transaction>
Dados de uma transação retornada pela consulta.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<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 PagSeguro às vendas registradas no seu sistema.

Presença: Opcional.
Tipo: Texto.
Formato: Livre, com o limite de 200 caracteres.
<transactionSearchResult>
<transactions>
<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.

CodigoSignificado
1Pagamento: 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.
<transactionSearchResult>
<transactions>
<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 abaixo.

CodigoSignificado
1Aguardando pagamento: o comprador iniciou a transação, mas até o momento o PagSeguro não recebeu nenhuma informação sobre o pagamento.
2Em análise: o comprador optou por pagar com um cartão de crédito e o PagSeguro está analisando o risco da transação.
3Paga: a transação foi paga pelo comprador e o PagSeguro já recebeu uma confirmação da instituição financeira responsável pelo processamento.
4Disponí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.
5Em disputa: o comprador, dentro do prazo de liberação da transação, abriu uma disputa.
6Devolvida: o valor da transação foi devolvido para o comprador.
7Cancelada: a transação foi cancelada sem ter sido finalizada.


Outros status menos relevantes foram omitidos. Em resumo, você deve considerar transações nos status de Paga para liberação de produtos ou serviços.

Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
<transactionSearchResult>
<transactions>
<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 PagSeguro.

ValorSignificado
INTERNALPagSeguro
EXTERNALInstituições Financeiras


Presença: Opcional (somente quando transactionStatus igual a 7).
Tipo: Texto.
Formato: Valores possíveis INTERNAL ou EXTERNAL.
<transactionSearchResult>
<transactions>
<transaction>
<paymentMethod>
Dados do meio de pagamento usado pelo comprador.
<transactionSearchResult>
<transactions>
<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 PagSeguro: o comprador optou por pagar a transação utilizando o saldo de sua conta PagSeguro.
5Oi Paggo(*): o comprador escolheu pagar sua transação através de seu celular Oi.
7Depósito em conta: o comprador optou por fazer um depósito na conta corrente do PagSeguro. Ele precisará ir até uma agência bancária, fazer o depósito, guardar o comprovante e retornar ao PagSeguro 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.


Os tipos marcados (*) não estão disponíveis para utilização.

Presença: Obrigatória.

Tipo: Número.

Formato: Inteiro.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<transaction>
<feeAmount>
Valor total das taxas cobradas.

Informa o valor total das taxas cobradas pelo PagSeguro nesta transação.

Presença: Obrigatória.
Tipo: Número.
Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.
<transactionSearchResult>
<transactions>
<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.
<transactionSearchResult>
<transactions>
<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.