GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
1
API de Consulta de Transações por
Código de Referência
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
2
Histórico de Versões
DATA
01/06/2014
DESCRIÇÃO
Visão Geral
Copyright
Todos os direitos reservados. O UOL é uma marca comercial do UNIVERSO ONLINE S / A. O logotipo
do UOL é uma marca comercial do UNIVERSO ONLINE S / A. Outras marcas, nomes, logotipos e
marcas são de propriedade de seus respectivos proprietários.
As informações contidas neste documento pertencem ao UNIVERSO ONLINE S/A. Todos os direitos
reservados. UNIVERSO ONLINE S/A. - Av. Faria Lima, 1384, 6º andar, São Paulo / SP, CEP 01452-002,
Brasil.
O serviço PagSeguro não é, nem pretende ser comparável a serviços financeiros oferecidos por
instituições financeiras ou administradoras de cartões de crédito, consistindo apenas de uma forma
de facilitar e monitorar a execução das transações de comércio electrónico através da gestão de
pagamentos. Qualquer transação efetuada através do PagSeguro está sujeita e deve estar em
conformidade com as leis da República Federativa do Brasil.
Aconselhamos que você leia os termos e condições cuidadosamente.
Aviso Legal
O UOL não oferece garantias de qualquer tipo (expressas, implícitas ou estatutárias) com relação às
informações nele contidas. O UOL não assume nenhuma responsabilidade por perdas e danos
(diretos ou indiretos), causados por erros ou omissões, ou resultantes da utilização deste documento
ou a informação contida neste documento ou resultantes da aplicação ou uso do produto ou serviço
aqui descrito. O UOL reserva o direito de fazer qualquer tipo de alterações a quaisquer informações
aqui contidas sem aviso prévio.
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
3
Índice
Histórico de Versões .............................................................................................................. 2
Copyright ................................................................................................................................ 2
Aviso Legal.............................................................................................................................. 2
Índice ...................................................................................................................................... 3
Introdução.............................................................................................................................. 4
API de Consulta por código de referência ............................................................................. 4
Parâmetros da API ............................................................................................................. 5
Resposta da API.................................................................................................................. 7
Parâmetros de resposta ..................................................................................................... 8
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
4
Introdução
Este documento descreve a API de Consulta de Transações por Código de Referência do
PagSeguro. Com esta API você pode consultar uma transação através do código de
referência atrelada a ela, ou seja, o código passado no campo reference.
API de Consulta por código de referência
A API de Consulta de Transações por Código de Referência funciona com ilustrado na Figura
abaixo:
Para consultar transações por código de referência, você deve fazer uma requisição à API de
Consulta de Transações informando o código desejado. O PagSeguro irá retornar todas as
transações que foram criadas com esse código. 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).
curl -k https://ws.pagseguro.uol.com.br/v2/transactions -d
“[email protected]
&token=2507D8278A9D478D94327BABDDC2A573
&reference=REF123456”
Também é possível definir uma data limite para a pesquisa.
curl -k https://ws.pagseguro.uol.com.br/v2/transactions -d
“[email protected]
&token=2507D8278A9D478D94327BABDDC2A573
&reference=REF123456”
&initialDate=2014-04-01T00:00
&finalDate=2014-04-20T00:00
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
5
Parâmetros da API
Abaixo são descritos os parâmetros usados na consulta a transações por código de
referência.
CAMPO
email
DESCRIÇÃO
E-mail da conta que chama a API.
Especifica o 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., [email protected]), associado à uma
conta PagSeguro do tipo Vendedor ou Empresarial, com no máximo 60
caracteres.
token
Token da conta que chama a API.
Informa o token correspondente à conta PagSeguro que está realizando a
chamada à API. Para criar um token para sua conta PagSeguro, acesse o site
do PagSeguro.
Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de 32 caracteres.
reference
Código identificador da transação.
Código informado na criação da transação para fazer referência ao
pagamento.
Presença: Obrigatória.
Tipo: Texto.
Formato: Livre, com no máximo 200 caracteres.
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: Opcional.
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.
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
finalDate
6
DESCRIÇÃO
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: Opcional.
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 código de referência
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.
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
7
Resposta da API
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.
1. <transactionSearchResult>
2.
<date>2011-02-16T20:14:35.000-02:00</date>
3.
<currentPage>1</currentPage>
4.
<resultsInThisPage>10</resultsInThisPage>
5.
<totalPages>1</totalPages>
6.
<transactions>
7.
<transaction>
8.
<date>2011-02-05T15:46:12.000-02:00</date>
9.
<lastEventDate>2011-02-15T17:39:14.000-03:00</lastEventDate>
10.
<code>9E884542-81B3-4419-9A75-BCC6FB495EF1</code>
11.
<reference>REF123456</reference>
12.
<type>1</type>
13.
<status>3</status>
14.
<paymentMethod>
15.
<type>1</type>
16.
</paymentMethod>
17.
<grossAmount>49900.00</grossAmount>
18.
<discountAmount>0.00</discountAmount>
19.
<feeAmount>0.00</feeAmount>
20.
<netAmount>49900.00</netAmount>
21.
<extraAmount>0.00</extraAmount>
22.
</transaction>
23.
<transaction>
24.
<date>2011-02-07T18:57:52.000-02:00</date>
25.
<lastEventDate>2011-02-14T21:37:24.000-03:00</lastEventDate>
26.
<code>2FB07A22-68FF-4F83-A356-24153A0C05E1</code>
27.
<reference>REF123456</reference>
28.
<type>3</type>
29.
<status>4</status>
30.
<paymentMethod>
31.
<type>3</type>
32.
</paymentMethod>
33.
<grossAmount>26900.00</grossAmount>
34.
<discountAmount>0.00</discountAmount>
35.
<feeAmount>0.00</feeAmount>
36.
<netAmount>26900.00</netAmount>
37.
<extraAmount>0.00</extraAmount>
38.
</transaction>
39.
</transactions>
40. </transactionSearchResult>
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
8
Parâmetros de resposta
A tabela abaixo descreve os elementos presentes em uma resposta com erros da API de
Cancelamento de Transações.
CAMPO
<transactionSearchResult>
DESCRIÇÃO
Este campo é a raiz do XML de resposta e engloba os dados dos
resultados da consulta.
Data da consulta.
Informa o momento em que a consulta foi realizada.
<transactionSearchResult>
<date>
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.
Índice da página atual.
<transactionSearchResult>
<currentPage>
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.
Número de resultados na página atual.
<transactionSearchResult>
<resultsInThisPage>
Indica o número de resultados presentes na página atual.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
Número total de páginas.
Informa o número total de páginas no resultado da busca.
<transactionSearchResult>
<totalPages>
VERSÃO 1.0.0
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
9
DESCRIÇÃO
<transactionSearchResult>
<transactions>
Representa as transações retornadas pela consulta.
<transactionSearchResult>
<transactions>
<transaction>
Dados de uma transação retornada pela consulta.
Data da criação da transação.
<transactionSearchResult>
<transactions>
<transaction>
<date>
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.
Data do último evento.
<transactionSearchResult>
<transactions>
<transaction>
<lastEventDate>
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.
Código identificador da transação
<transactionSearchResult>
<transactions>
<transaction>
<code>
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.
Código de referência da transação.
<transactionSearchResult>
<transactions>
<transaction>
<reference>
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.
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
10
DESCRIÇÃO
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.
Código
<transactionSearchResult>
<transactions>
<transaction>
<type>
1
Significado
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.
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.
Código
<transactionSearchResult>
<transactions>
<transaction>
<status>
VERSÃO 1.0.0
Significado
1
Aguardando pagamento: o comprador iniciou a transação,
mas até o momento o PagSeguro não recebeu nenhuma
informação sobre o pagamento.
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.
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.
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.
5
Em disputa: o comprador, dentro do prazo de liberação da
transação, abriu uma disputa.
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
11
DESCRIÇÃO
6
Devolvida: o valor da transação foi devolvido para o
comprador.
7
Cancelada: 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.
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.
<transactionSearchResult>
<transactions>
<transaction>
Valor
Significado
INTERNAL
PagSeguro
EXTERNAL
Instituições Financeiras
<cancellationSource>
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.
Tipo do meio de pagamento.
<transactionSearchResult>
<transactions>
<transaction>
<type>
VERSÃO 1.0.0
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.
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
12
DESCRIÇÃO
Código
Significado
1
Cartão de crédito: o comprador escolheu pagar a transação
com cartão de crédito.
2
Boleto: o comprador optou por pagar com um boleto
bancário.
3
Débito online (TEF): o comprador optou por pagar a
transação com débito online de algum dos bancos
conveniados.
4
Saldo PagSeguro: o comprador optou por pagar a transação
utilizando o saldo de sua conta PagSeguro.
5
Oi Paggo *: o comprador escolheu pagar sua transação
através de seu celular Oi.
* Os tipos marcados não estão disponíveis para utilização.
Presença: Obrigatória.
Tipo: Número.
Formato: Inteiro.
Valor bruto da transação.
<transactionSearchResult>
<transactions>
<transaction>
<grossAmount>
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.
Valor do desconto dado.
<transactionSearchResult>
<transactions>
<transaction>
<discountAmount>
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.
VERSÃO 1.0.0
GUIA DE INTEGRAÇÃO DA API DE CONSULTA DE TRANSAÇÕES
CAMPO
13
DESCRIÇÃO
Valor total das taxas cobradas.
<transactionSearchResult>
<transactions>
<transaction>
<feeAmount>
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.
Valor líquido da transação.
<transactionSearchResult>
<transactions>
<transaction>
<netAmount>
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.
Valor extra.
<transactionSearchResult>
<transactions>
<transaction>
<extraAmount>
VERSÃO 1.0.0
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.