Serviço de Cancelamento de Transações

Visão Geral

Aprenda a realizar cancelamento de transações no PagSeguro. Esta API pode ser usada para cancelar transações recebidas pelo sistema ou loja pelo PagSeguro.

Serviço de Cancelamento de Transações

O Serviço de Cancelamento de Transações funciona com ilustrado na Imagem 1.

Imagem 1

Utilizando o Serviço de Cancelamento de Transações do PagSeguro.

Para cancelar uma transação, informe o e-mail da loja cadastrada, o token de sua aplicação e o código da transação a ser cancelada. O sistema do PagSeguro irá realizar o cancelamento e retornar o resultado da operação. Uma melhor descrição dos parâmetros e do retorno estão descritos a seguir.

Parâmetros da API

Para cancelar uma transação, você deve fazer uma requisição ao Serviço de Cancelamento de Transações, no endpoint: https://ws.pagseguro.uol.com.br/v2/transactions/cancels informando os parâmetros descritos abaixo. Veja abaixo um exemplo de chamada à API, que requer a utilização do protocolo HTTP e o método POST (as linhas foram quebradas para facilitar a leitura).

curl -k https://ws.pagseguro.uol.com.br/v2/transactions/cancels -d
“email=api@cancelamento.com
&token=2507D8278A9D478D94327BABDDC2A573
&transactionCode=2748FC6F-A636-465D-9FA1-A6701477D57C”

Veja na Referência da API:

Abaixo são descritos os parâmetros usados no cancelamento de transações.

PARÂMETRO DESCRIÇÃO
email 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., usuario@site.com.br), 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 a conta PagSeguro, se logue no site do PagSeguro e, logo após clique aqui.

Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de 32 caracteres.
transactionCode Código que identifica a transação a ser cancelada.

Para que uma transação possa ser cancelada, no momento da requisição seu status deve ser: Aguardando pagamento ou Em análise.

Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de 36 caracteres, com os hífens, ou 32 caracteres, sem os hífens.

Resposta da API

A resposta da requisição ao Serviço de Cancelamento de Transações é dada em formato XML. Caso a operação tenha sucesso, o retorno é o XML abaixo:

<?xml version=”1.0” encoding=”ISO-8859-1” standalone=”yes”?>
<result>OK</result>

Caso ocorra algum erro na chamada ao Serviço de Cancelamento de Transações, seja algum erro nos parâmetros informados ou alguma falha técnica no sistema, uma resposta de erro será retornada, como no exemplo abaixo. Ela indicará todos os erros identificados na chamada.

<?xml version=”1.0” encoding=”ISO-8859-1” standalone=”yes”?>
<errors>
    <error>
        <code>56002</code>
        <message>invalid transaction status to cancel.</message>
    </error>
</erros>

A tabela abaixo descreve os elementos presentes em uma resposta com erros do Serviço de Cancelamento de Transações.

PARÂMETRO DESCRIÇÃO
<errors> Raiz do arquivo XML de resposta de erros. Contém a lista de erros encontrados.
<errors>
<error>
Descreve um erro encontrado durante o processamento do Serviço de Cancelamento.
<errors>
<error>
<code>
Código do erro.

Identifica a natureza do erro encontrado e permite o tratamento do erro pelo seu sistema.

Tipo: Número.
Formato: Veja a tabela de erros do Serviço de Cancelamento de Transações na Seção Error! Reference source not found..
<errors>
<error>
<message>
Descrição do erro.

Descreve o erro encontrado para que ele seja compreendido pelo desenvolvedor.

Tipo: Texto.
Formato: Veja a tabela de erros do Serviço de Cancelamento de Transações na Seção Error! Reference source not found.

Tabela de Erros

Caso sua aplicação informe algum dado incorreto ou fora do padrão esperado pela aplicação, será retornado uma mensagem informando o problema. Confira abaixo os erros que podem ser retornados:

HTTP 401 - Unauthorized Ocorre quando sua aplicação encaminhou uma credencial (e-mail ou token) invalida ou inexistente.

HTTP 405 – Method Not Allowed Ocorre quando sua aplicação efetuou a chamada utilizando um método não esperado. Neste caso verifique se o método da chamada é GET ou POST.

HTTP 415 – Cannot consume content type Ocorre quando não é encaminhado o Content-Type na chamada.

HTTP 400 – Bad Request Ocorre quando um ou mais dados foram encaminhados de forma incorreta ou fora do padrão. Este retorno possui um XML no corpo na mensagem que identifica quais os erros presentes na chamada. O XML possui o seguinte formato:

PARÂMETRO DESCRIÇÃO
56001 transaction is not found.
56002 invalid transaction status to cancel.
56003 transactionCode is required
56004 transactionCode invalid pattern.