Pagamento Recorrente Transparente

Com a API de Pagamento Recorrente Transparente, sua aplicação pode efetuar cobranças recorrentes de maneira fácil e sem a necessidade do redirecionamento do cliente para o PagSeguro.

O Pagamento Recorrente está disponível para as contas Vendedor e Empresarial e aceita somente pagamento com cartão de crédito.

1. Como Funciona?

Detalhamos a seguir as regras de funcionamento do Pagamento Recorrente. Se preferir, acesse diretamente os Endpoints da API.

Com o Pagamento Recorrente você cria um plano, definindo as regras de cobrança, periodicidade, valor, entre outros. Com o plano criado, sua aplicação registra os compradores para serem cobrados no plano desejado.

Por exemplo, se o plano for mensal, seu cliente irá realizar a adesão somente uma vez e ele será cobrado mensalmente sem precisar realizar nenhuma outra ação. Além disso, você pode definir desconto para a próxima cobrança, listar pagamentos de um plano, efetuar a retentativa de pagamento para cartões de crédito que falharam no momento da cobrança, mudar o status de uma adesão (suspender ou reativar) e também trocar o seu meio de pagamento.

Modalidades de Cobrança

O PagSeguro possui 2 modalidades de cobrança:

  • Plano Automático
  • Plano Personalizado

Plano Automático - Gestão da Recorrência via PagSeguro

Nesta modalidade, você define a periodicidade e detalhes de cobrança, e o PagSeguro se encarrega de efetuar todas as cobranças nas datas especificadas.

Importante: Para planos automáticos aceitamos apenas cartão de crédito como meio de pagamento.

Fluxo básico da recorrência automática:

  • Cliente adere ao plano e informa dados do cartão de crédito
  • PagSeguro efetua transação de cartão no valor da parcela do plano
  • Primeira cobrança da vigência do plano é criada
  • Plano de recorrência fica ativo para o cliente
  • Após o período de vigência, o PagSeguro irá realizar nova cobrança no cartão do cliente automaticamente.

Fluxo Recorrência Automática

Para auxiliar sua gestão de cobranças, você poderá implementar a consulta de ordens de pagamento por meio do serviço Listar Ordens de Pagamento. Por meio deste serviço é possível consultar o status de pagamento de cada ordem (parcela).

Plano Personalizado – Gestão da Recorrência via Vendedor

Nesta modalidade, o PagSeguro não efetua a gestão da recorrência. Portanto, nas datas definidas no plano, a sua aplicação deverá fazer uma chamada ao serviço de solicitação de pagamento para realizar a cobrança, ou seja, a cada período estabelecido, o vendedor deverá fazer as chamadas de cobrança para o PagSeguro.

Fluxo básico da recorrência personalizada:

  • Cliente adere ao plano e informa dados cartão de crédito
  • PagSeguro efetua transação validadora (no valor de R$ 1,50) apenas para verificar a validade do cartão
  • Transação validadora é estornada
  • Plano de recorrência fica ativo para o cliente
  • Aplicação do vendedor realizada chamada ao serviço de cobrança nas datas de renovação de pagamento.

Fluxo Recorrência Personalizada

Para auxiliar sua gestão de cobranças, você poderá implementar a consulta de ordens de pagamento por meio do serviço Listar Ordens de Pagamento. Por meio deste serviço é possível consultar o status de pagamento de cada ordem (parcela).

Retentativa de Pagamento

O PagSeguro possibilita que transações sem sucesso sejam submetidas a retentativa de pagamento. Dessa forma, antes de recorrer a outras formas de pagamento, você pode tentar novamente a cobrança no cartão de crédito de seus clientes.

Existem três formas de retentativa de pagamento. E essas são distintas para Planos Automáticos e Planos Personalizados, veja abaixo.

a) Retentativa Automática - Válida apenas para planos automáticos

Para cobranças sem sucesso por motivo que não sejam cartão cancelado ou vencido, como por exemplo limite de crédito excedido, o PagSeguro poderá realizar uma única retentativa após 3 dias da não aprovação da transação.

Se esta cobrança falhar novamente, ela permanecerá aberta, ficando a cargo do vendedor tomar medidas.

Essa funcionalidade deve ser habilitada dentro do Painel na página do PagSeguro >> Minha Conta >> Pagamento Recorrente >> Planos.

b) Retentativa Manual - Válida para planos automáticos e personalizados

  • Botão via Painel: No Painel, ao acessar o menu Pagamento Recorrente >> Adesões, caso hajam adesões com pagamento pendente, é exibido um botão para uma listagem de pagamentos pendentes. Ao entrar nesta listagem, um outro botão permite que você submeta as adesões não pagas para a fila de retentativa. O botão fica disponível um dia após a transação não ser aprovada.

Esta fila será processada até 3 vezes sendo retentada uma vez por dia. Após isso, o botão fica indisponível no Painel. Note que a retentativa por botão sobrepõe a retentativa automática.

  • API: O serviço de retentativa de pagamento pode ser chamado quantas vezes forem necessárias, porém a cobrança será realizada somente se a ordem de pagamento da adesão estiver com o status “Não Pago”, que sinaliza que já foi realizada uma tentativa de pagamento sem sucesso.

c) Retentativa por Mudança de Meio de Pagamento - Válido apenas para Planos Automáticos

Se o cartão estiver vencido ou cancelado durante a renovação da recorrência, a adesão passa para o status "Troca de Meio de Pagamento" (Status M) sinalizando que é necessário que o cliente atualize seu cartão (veja Mudança de Meio de Pagamento).

Assim quando seu cliente acessar o Painel do PagSeguro e alterar o cartão de uma adesão com status "Troca de Meio de Pagamento", automaticamente é realizada uma retentativa de pagamento para a última cobrança que ficou com pagamento em aberto. Caso esta retentativa tenha sucesso, a adesão retorna ao status Ativo (Status A).

Se houver mais de uma cobrança em aberto, a retentativa irá se aplicar somente à última cobrança. As outras precisarão ser regularizadas à parte, fora do sistema de recorrência.

Se a ordem de pagamento vencer na data atual e seu cliente atualizar o cartão na mesma data, a cobrança será agendada para o dia seguinte. Porém se a ordem já estiver vencida e o cliente atualizar o cartão, a cobrança será agendada para a mesma data.

Especificações Funcionais

Máquina de Status das Adesões

Como a recorrência é um ciclo de vida constante de transações, criamos a Máquina de Status das Adesões, para você acompanhar e gerenciar todo esse ciclo, desde uma adesão iniciada, até seu cancelamento.

Segue abaixo o fluxo do ciclo de vida de uma adesão.

Máquina de Status

Regras para criação de Planos

Os planos são utilizados para recorrências que aceitam somente cartão de crédito. Para realizar as adesões precisamos primeiro criar estes planos.

Não há a necessidade de se criar um plano para cada adesão, o ideal é agregar vários pagamentos de vários consumidores dentro de um mesmo plano.

Cada parâmetro a ser enviado para a API está descrito na documentação. Porém detalhamos as regras funcionais para a criação de planos que atendem tanto ao plano automático como ao plano personalizado.

Redirecionamento de URL para adesão via botão

No Pagamento Recorrente do PagSeguro é possível criar um botão de pagamento que pode ser compartilhado em seus sites. A gestão desses botões é via Painel (área logada do site PagSeguro - na aba Pagamento Recorrente).

Você pode criar planos integrando com a nossa API e copiar o código do botão disponível no Painel - em detalhes do plano - para disponibilizá-lo em seus sites.

Dessa forma, seu cliente que deseja aderir ao plano de recorrência, ao clicar no botão será direcionado para a página do PagSeguro para finalizar sua assinatura.

Durante esse processo, disponibilizamos algumas URLs de direcionamento para que o cliente revise seu carrinho e/ou seja direcionado ao seu site no final da adesão.

redirectURL: URL para onde o assinante será redirecionado após a finalização do fluxo de pagamento.

reviewURL: URL para onde o assinante será redirecionado, durante o fluxo de pagamento, caso o mesmo queira alterar/revisar as regras da assinatura.

Período Trial

Para configurar um período de teste no plano, enviar o parâmetro trialPeriodDuration na chamada do método de Criação de Plano.

O período de teste configura o número de dias que o cliente poderá usufruir gratuitamente do plano. Ao aderir a um plano com trial, o status da adesão irá se tornar Ativo, mas não haverá nenhuma cobrança enquanto o período trial não finalizar.

A cobrança será realizada no dia seguinte ao término do período trial e somente a partir de então, a periodicidade da recorrência irá iniciar (semanal, mensal, etc).

Taxa de Adesão

Para cobrar taxa de adesão, matrícula ou outra taxa extra além da cobrança recorrente no ato da adesão, enviar o parâmetro membershipFee na chamada do método de Criação de Plano..

O valor da taxa de adesão é cobrado adicionalmente, não tendo relação com o valor das parcelas da recorrência.

Como funciona a cobrança de taxa de adesão:

a) Plano sem período trial: é cobrada no ato da adesão o valor da taxa + valor da primeira parcela de recorrência, como se fosse um débito só.

b) Plano com período trial: é cobrada junto com a primeira parcela da recorrência somente após o final do período trial.

Regras de Expiração de Plano e Adesão

Ao criar um plano, é possível configurar se ele terá uma data, prazo ou número de adesões limite.

Após o plano ter seu status expirado, nenhuma cobrança é realizada e nenhuma nova adesão pode ser feita.

a) Expiração por Data: Assim que chegar a data informada de encerramento, o Plano será expirado (Status E) e todas as suas adesões também serão expiradas, não importando há quanto tempo a adesão foi criada. A partir da data enviada no parâmetro nenhuma nova cobrança será efetuada e nenhuma adesão poderá ser feita ao plano a partir dessa data.

Para saber mais sobre os status dos planos, veja a Tabela de Status de Plano.

Exemplo:

Plano Mensal sem período trial
Criação: 01/Julho
Expiração: 30/Setembro

Adesão 1
Data da adesão: 08/Jul
Adesão expirada: 30/Set

Adesão 2
Data da adesão: 17/Ago
Adesão expirada: 30/Set

Adesão 3
Data da adesão: 21/Set
Adesão expirada: 30/Set

Ciclo de adesões

b) Expiração por prazo: Permite configurar um prazo de vigência de uma adesão - dados em valor e período. Por exemplo: 7 meses, 90 dias, 1 ano. A vigência é calculada individualmente para cada adesão a partir da data em que for realizada. Assim que cada adesão completa o período, ela é expirada (Status E), mas o plano continua ativo (Status A).

Importante: Não é possível utilizar os parâmetros de expiração por prazo em conjunto com o de expiração por data na aplicação.

Exemplo 1:

Plano Mensal sem período trial
Prazo da Adesão: 5 meses
Data da Adesão: 10/Julho

Expiração por prazo Exemplo 1

Exemplo 2:

Plano mensal e com 30 dias de período trial
Prazo da Adesão: 5 meses
Data da Adesão: 10/Julho

Expiração por prazo Exemplo 2

As cobranças serão iniciadas após os 30 dias cedidos de período teste, e iniciarão exatamente ao fim desse período, seguindo pelos próximos 5 meses, sendo finalizadas em 10/dez.

c) Expiração por número máximo de adesões: Permite estabelecer um limite máximo de inscritos no plano. Após isso, o plano não irá aceitar novas adesões, mantendo ativas as adesões já realizadas.

É possível combinar este parâmetro com o de expiração por data ou por prazo, se você tiver necessidade de que as adesões também sejam expiradas após um período de tempo.

Regras de Cobrança

É possível impedir que uma adesão seja cobrada acima de um valor máximo estabelecido. Essa trava pode ser configurada tanto para o valor total do período de vigência (semanal, mensal, etc), quanto o valor total para toda a vigência das adesões. A restrição também pode ser aplicada por quantidade de pagamentos, ao invés do valor.

Na modalidade de Plano Personalizado é possível criar planos com valor de cobrança em aberto, **onde este valor é definido apenas no momento da chamada à API de cobrança (veja a referência da API) – dessa forma é possível que você envie cobranças com valores diferentes a cada “parcela” caso seu plano não seja de um valor fixo. Para evitar que o cliente seja cobrado acima do valor contratado, ao criar o plano você deve informar as configurações de limite. Após a criação do plano, estas configurações não podem ser alteradas.

A restrição de valor máximo por período de vigência só é aceita em planos do tipo Personalizado. Essa configuração pode ser utilizada para evitar cobranças indevidas ou em duplicidade. Quando a adesão atingir o limite máximo configurado, qualquer chamada à API de cobrança não gerará mais nenhuma ordem de pagamento.

No caso do limite máximo por período, a permissão de cobrança é renovada a cada ciclo novo de recorrência (na próxima semana, ou próximo mês, por exemplo, dependendo da vigência escolhida para o plano).

Restrição de valor

Regras de Cancelamento da adesão

Qualquer adesão com status A (ativa) pode ser cancelada tanto pelo vendedor, quanto pelo comprador via Painel - nos detalhes de uma adesão. Porém o PagSeguro possibilita que o vendedor configure o botão “Cancelar Assinatura” do comprador com uma URL de direcionamento, ou seja, quando o cliente tentar cancelar sua adesão ao plano, ele será direcionado ao seu site conforme pré-definido no parâmetro.

O parâmetro cancelURL pode ser configurado somente durante a criação do plano. Com isso, o comprador que tentar efetuar o cancelamento de sua adesão via Painel (área logada), será redirecionado à URL parametrizada e continuará com a adesão ativa até que o vendedor efetue alguma ação.

Se, durante a criação do plano não for informado nenhum parâmetro cancelURL, o comprador poderá cancelar sua adesão a qualquer momento no Painel, e sua adesão passará a ter o status C (cancelada).

Para cancelar uma adesão diretamente via API, ver serviço: Cancelamento de adesões.

Edição de Valor em Planos

O PagSeguro possibilita que você atualize o valor de seus planos recorrentes. Essa funcionalidade permite que o novo valor seja aplicado apenas à novas adesões, ou a todos os seus clientes, ou seja, tanto nos clientes atuais já aderentes ao plano, quanto para as novas adesões.

Essa alteração ainda pode ser feita, tanto pelo detalhe de um plano dentro do Painel do PagSeguro, como via API, conforme detalhado no item Edição de Valor em Planos via API.

Mudança de Meio de Pagamento

Uma adesão pode ter seu status alterado para Troca de Meio de Pagamento (Status M), se durante a cobrança de uma recorrência for identificado que o cartão do cliente está vencido ou cancelado.

Quando a adesão passa a ter este status, tanto o comprador quanto o vendedor recebem um email do PagSeguro notificando que um novo cartão precisa ser cadastrado para que as cobranças continuem.

Para alterar o cartão, o cliente precisa acessar sua conta PagSeguro. Ao salvar um novo cartão, automaticamente será realizada uma retentativa de pagamento para a última cobrança que ficou com pagamento em aberto. Caso esta retentativa tenha sucesso, a adesão retorna ao status Ativo (Status A).

Em caso de haver mais de uma cobrança em aberto quando o cliente cadastrar um cartão válido, a retentativa irá se aplicar somente à última cobrança. As outras precisarão ser regularizadas à parte, fora do sistema de recorrência.

Enquanto a adesão estiver com status M - Troca de Meio de Pagamento - continuam valendo a contagem de prazo de expiração, duração da adesão e todas as configurações originais do plano, porém nenhuma cobrança é realizada, ficando a cargo do vendedor contatar o comprador para regularizar seus dados.

2. Endpoints da API

Autenticação

Antes de entrarmos nos detalhes de cada serviço, vamos entender como funciona a autenticação. Todas as chamadas para os serviços do PagSeguro necessitam de uma autenticação, que pode ser efetuada de duas maneiras:

Autenticação para vendedores

Este modelo utiliza o e-mail e token do vendedor como forma de autenticação. Os parâmetros devem ser passados ao fim da URL do serviço, conforme exemplo abaixo:

Ex: https://{caminho do serviço}?email={seu email}&token={seu token}

Para saber qual é o seu token, consulte o seu Painel.

Autenticação para Modelo de Aplicações

Este modelo de autenticação é voltado para sistemas que utilizam o modelo de aplicações do PagSeguro. A autenticação neste caso utiliza o ID e a chave da aplicação do vendedor.

Para algumas chamadas também é necessário o código de autorização do vendedor. Os parâmetros devem ser passados ao fim da URL do serviço, conforme exemplo abaixo:

Ex: https://{caminho do serviço}?appId={id da aplicação}&appKey={chave da aplicação}&authorizationCode={código de autorização}

Para verificar as suas aplicações cadastradas, consulte o seu Painel.

Atenção: Em ambos os casos, por questões de segurança, recomenda-se não expor estes parâmetros no front-end do seu sistema. Sendo assim, as chamadas para os serviços de integração que exigem autenticação devem ser feitos diretamente do back-end.

Formato de dados para envio e resposta

Os serviços do PagSeguro oferecem a possibilidade de se trabalhar tanto com o formato JSON quanto com o formato XML, seja para entrada ou para saída. Além disso, também é possível enviar os dados diretamente na URL da requisição. Para tal, deve-se explicitar no cabeçalho (header) da chamada HTTP os seguintes parâmetros:

Content-type

application/xml;charset=ISO-8859-1 - Utilize este valor para enviar dados em formato XML
application/json;charset=ISO-8859-1 - Utilize este valor para enviar dados em formato JSON
application/x-www-form-urlencoded;charset=ISO-8859-1 - Utilize este valor para enviar os dados na URL

Accept

application/vnd.pagseguro.com.br.v3+xml;charset=ISO-8859-1 - Utilize este valor para receber a resposta em formato XML
application/vnd.pagseguro.com.br.v3+json;charset=ISO-8859-1 - Utilize este valor para receber a resposta em formato JSON

Por exemplo, se na sua aplicação você necessita enviar os dados em formato JSON e receber as respostas em formato XML, utilize os seguintes headers na sua chamada HTTP:

Content-type: application/json;charset=ISO-8859-1
Accept: application/vnd.pagseguro.com.br.v3+xml;charset=ISO-8859-1

Pode-se intercambiar estes valores conforme a sua necessidade, como também modificá-los a cada chamada de serviço.

Atenção: Independentemente do formato de dados utilizado, a codificação de caracteres padrão para a integração é a ISO-8859-1. Tome o cuidado de sempre enviar os dados com este encoding de caracteres. Os dados enviados pelo PagSeguro sempre estarão neste encoding.

Sandbox

Todos os serviços que serão citados abaixo mostram a URL de produção, que é https://ws.pagseguro.uol.com.br/. Para fazer a chamada aos serviços utilizando o Sandbox, basta trocar a URL por https://ws.sandbox.pagseguro.uol.com.br/.

Iniciando uma sessão de pagamento

Após a criação do(s) seu(s) plano(s), precisamos preparar o sistema para fazer uma adesão a um plano existente. O primeiro passo do fluxo de pagamento é a criação da sessão de pagamento. Assim que o usuário do seu site for realizar um pagamento, precisamos recuperar um ID de sessão com o PagSeguro.

Para gerar um ID de sessão válido, utilize o método /sessions (veja a documentação)

URL: POST https://ws.pagseguro.uol.com.br/sessions{autenticação}

O método irá retornar o ID da sessão. Coloque esse ID no seu contexto de página, pois ele será utilizado nas chamadas Javascript que documentamos a seguir.

Integrações no browser

A API do Pagamento Transparente, que é a forma de pagamento não recorrente, possui funções JavaScript para algumas operações que devem ser executadas no browser do cliente, a fim de se obter a adesão a um plano. Para ter acesso a essas funções, uma API JavaScript deve ser importada no final da página de pagamento do seu site. Como esta API é documentada em outra sessão desta documentação, colocaremos abaixo os passos que devem ser seguidos e os links para a documentação da API.

Os passos que devem ser seguidos são:

  1. Incluir a API Javascript na página de pagamento
  2. Setar o ID da sessão gerado anteriormente
  3. Obter o token do cartão de crédito

Além destes passos obrigatórios, existem outros métodos auxiliares que podem lhe ajudar com outras tarefas, inclusive para enriquecer a experiência do seu usuário. São eles:

  • Obter os meios de pagamento - Com este método é possível obter, dentre outras informações, caminhos para imagens que representam os diversos meios de pagamento aceitos pelo PagSeguro. Mas lembre-se: no pagamento recorrente, apenas o método Cartão de Crédito é aceito.

  • Obter bandeira do cartão de crédito - Com este método é possível saber, após digitados seis dígitos do cartão, qual é a bandeira do cartão.

  • Obter identificação do comprador - Pode-se utilizar o hash gerado aqui como parâmetro no método /pre-approvals, que é o método que cria a recorrência (adesão a um plano). O método citado requer ou o IP do assinante, que você deve obter por seus próprios meios, ou este hash. Fique à vontade para usar o que preferir.

De posse do token do cartão de crédito, e também da identificação do comprador (hash) caso tiver optado por ela, já podemos prosseguir para a adesão.

Criação do plano

O primeiro passo para criar adesões é criar um plano. Os parâmetros estão descritos na documentação do método. As regras funcionais sobre como utilizar os parâmetros, conforme sua necessidade de negócio, estão explicadas na Regras para criação de Planos.

URL: POST https://ws.pagseguro.uol.com.br/pre-approvals/request{autenticação}

O método irá retornar o código do plano criado. Usaremos este código para fazer a adesão ao plano.

Os planos criados podem ser visualizados no seu Painel.

Os planos personalizados permitem que não seja informado o campo amountPerPayment que informa o valor a ser cobrado na recorrência. Essa configuração permite que sejam realizadas chamadas de cobrança de valores variáveis.

Atenção: Nos planos personalizados, a responsabilidade de fazer o pedido de cobrança é do vendedor. Caso não haja condições de adequar seu sistema para enviar a chamada ao serviço de cobrança nos momentos corretos, opte pelo plano Automático, (charge = AUTO). Para mais informações veja sobre as Regras de Planos.

Exemplo: Para criar um plano Automático com cobranças mensais de R$ 100,00 por durante 1 ano:

{
    "preApproval": {
        "name": "Assinatura da Revista Fictícia",
        "charge": "AUTO",
        "period": "MONTHLY",
        "amountPerPayment": 100.00,
        "expiration": {
            "value": 1,
            "unit": "YEARS"
        }
    },
    "receiver": {
        "email": "seu@email.com.br"
    }
}

Exemplo: Para criar um plano pós-pago (Cobrança Manual) com cobranças semanais de R$ 10,00 a serem efetuadas toda Segunda-feira, com duração ilimitada, e taxa de adesão de R$ 50,00:

{
      "preApproval": {
        "name": "Acesso ao Site Fictício",
        "charge": "MANUAL",
        "period": "WEEKLY",
        "amountPerPayment": 10.00,
        "membershipFee": 50.00,
        "maxAmountPerPeriod": 50.00,
        "maxPaymentsPerPeriod": 5,
        "dayOfWeek": "MONDAY"
      },
      "receiver": {
        "email": "seu@email.com.br"
      }
}

Adesão ao plano

A adesão é o mecanismo que une o consumidor ao plano, possibilitando que ele faça os pagamentos de forma recorrente, de acordo com o que foi estipulado no plano ao qual ele está aderindo.

Note que você irá precisar do token de cartão gerado no passo 3 do tópico Integrações no Browser.

Para criar uma adesão utilize o método /pre-approvals (veja a documentação).

URL: POST https://ws.pagseguro.uol.com.br/pre-approvals{autenticação}

O método retorna o código da adesão. Guarde-o para cada adesão efetuada, pois ele será necessário para referenciá-las nos métodos que estão documentados a seguir.

As adesões podem ser visualizadas no seu Painel.

Cobrança de plano Automático

A cobrança de planos automáticos é efetuada pelo PagSeguro na periodicidade configurada na criação do plano, não necessitando realizar nenhuma chamada ao método.

Cobrança de plano Personalizado

Na data estipulada para cobrança, deve ser feita uma chamada a este serviço. Qualquer chamada que esteja divergente das configurações do plano no qual a cobrança será efetuada - por exemplo, na data errada ou com outro valor - será recusada.

Para efetuar uma cobrança personalizada, utilize o método /pre-approvals/payment (veja a documentação)

URL: POST https://ws.pagseguro.uol.com.br/pre-approvals/payment{autenticação}

O método retorna o código da transação de cobrança efetuada.

Caso o plano personalizado tenha sido criado sem valor pré-configurado, é necessário enviar também o parâmetro valor. Esta funcionalidade permite que o valor seja variável para cada cobrança.

Atenção: O PagSeguro não verifica se a cobrança da recorrência já foi feita para determinada vigência do plano. Se a aplicação enviar uma mesma cobrança duas vezes, a recorrência será cobrado em duplicidade. Esta verificação deverá existir na aplicação do vendedor. A não ser que o valor máximo de cobrança do período seja ultrapassado (ammount).

Suspensão e Reativação

Com este método é possível alterar o status de uma adesão, movendo-a de ativa (Status A) para suspensa (Status H) e vice-versa. Uma adesão não terá cobranças durante período em que estiver suspensa.

Se durante este tempo o plano expirar, ou o prazo da adesão encerrar, a adesão não poderá mais ser retornada para Ativa.

Para alterar o estado de uma adesão, utilize o método /pre-approvals/{preApprovalCode}/status (veja a documentação)

URL: PUT https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/status{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método /pre-approvals já documentado em Adesão ao Plano.

A resposta deste método não possui corpo.

Cancelamento de adesão

Com este serviço é possível solicitar o cancelamento de uma adesão. Note que, para o cancelamento ser efetuado, é necessário que a adesão esteja ativa (status A).

Para solicitar o cancelamento de uma adesão, utilize o método /pre-approvals/{preApprovalCode}/cancel (veja a documentação)

URL: PUT https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/cancel/{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método **/pre-approvals já documentado em Adesão ao Plano.

Atenção: O cancelamento da adesão não pode ser desfeito.

A resposta deste método não possui corpo.

Edição de Valor em Planos

É possivel editar valor de cobrança de planos ja criados. Para isso utilize o método /pre-approvals/request/{preApprovalRequestCode}/payment (veja a documentação)

URL: PUT https://ws.pagseguro.uol.com.br/pre-approvals/request/{preApprovalRequestCode}/payment{autenticação}

Desconto no pagamento

É possível conceder desconto para a próxima parcela da adesão. O desconto se aplica somente à cobrança subsequente, não se aplicando às demais cobranças futuras.

Para prover um desconto à próxima cobrança de uma adesão, utilize o método /pre-approvals/{preApprovalCode}/discount (veja a documentação)

URL: PUT https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/discount{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método **/pre-approvals já documentado em Adesão ao Plano.

A resposta deste método não possui corpo.

Mudança de meio de pagamento

Durante a vigência de uma adesão ativa é possível atualizar os dados de pagamento da adesão.

Para alterar os dados de pagamento, utilize o método /pre-approvals/{preApprovalCode}/payment-method (veja a documentação)

URL: PUT https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/payment-method{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método /pre-approvals já documentado em Adesão ao Plano.

A resposta deste método não possui corpo.

Listar ordens de pagamento

A cada intervalo de recorrência nos planos automáticos, o PagSeguro irá gerar uma Ordem de Pagamento. Ela indica a necessidade de cobrança da próxima parcela. Na data de vencimento da ordem de pagamento, será gerada uma Transação, que é a cobrança dessa ordem.

Se a transação for bem sucedida, a Ordem de Pagamento fica com o status 5 (Paga). Caso contrário, podem ser geradas novas tentativas de cobrança, através de novas Transações, dentro da mesma Ordem de Pagamento.

Com este método é possível verificar todas as Ordens de Pagamento geradas para uma adesão, bem como as Transações associadas a cada Ordem de Pagamento. A partir destes dados pode-se verificar se as cobranças foram efetuadas ou não, e por qual motivo.

Para listar as ordens de pagamento de uma adesão, utilize o método /pre-approvals/{preApprovalCode}/payment-orders (veja a documentação)

URL: GET https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/payment-orders{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método /pre-approvals já documentado em Adesão ao Plano.

O retorno deste método pode ser paginado, verifique na referência da API os parâmetros de entrada.

Os status de ordem de pagamento podem ser vistos na Tabela de Status de Ordem de Pagamento.

Os status das transações podem ser vistos na Tabela de Status de Transação.

Retentativa de pagamento

Para uma Ordem de Pagamento que não tenha sido cobrada com sucesso, pode-se solicitar a retentativa de cobrança através deste serviço. Isto irá gerar uma nova transação para esta Ordem de Pagamento.

A geração da cobrança não é instantânea, a chamada ao serviço irá colocar a ordem de pagamento em uma fila de retentativas.

Para solicitar a retentativa de cobrança, utilize o método /pre-approvals/{preApprovalCode}/payment-orders/{paymentOrderCode}/payment (veja a documentação)

URL: POST https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}/payment-orders/{paymentOrderCode}/payment{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método /pre-approvals já documentado em Adesão ao Plano.

O parâmetro {paymentOrderCode} é o código da ordem de pagamento a ser retentada. É obtido no método já documentado em Listar ordens de pagamento.

Para uma ordem ser retentada, ela precisa estar com status "Não pago" (status 6). Veja aqui todos os status de uma ordem de pagamento.

O método retorna o código da nova transação.

Consulta pelo código da Adesão

Esta consulta possibilita o acesso a todos os dados de uma adesão a partir de seu código identificador.

Para recuperar os dados de uma adesão, utilize o método /pre-approvals/{preApprovalCode} (veja a documentação).

URL: GET https://ws.pagseguro.uol.com.br/pre-approvals/{preApprovalCode}{autenticação}

O parâmetro {preApprovalCode} é o código da adesão obtido no método /pre-approvals já documentado em Adesão ao Plano.

No retorno, o status da adesão pode ser lido de acordo com a Tabela de Status de Adesão.

Consulta por intervalo de datas

Esta consulta possibilita o acesso aos dados de todas as recorrências criadas dentro do intervalo de datas fornecido como parâmetro. Note que a consulta não retorna resultados para datas anteriores a 6 (seis) meses da data atual.

Para recuperar os dados das recorrências, utilize o método /pre-approvals (veja a documentação).

URL: GET https://ws.pagseguro.uol.com.br/pre-approvals{autenticação}

O retorno deste método pode ser paginado, verifique na referência da API os parâmetros de entrada.

No retorno, o status da recorrência pode ser lido de acordo com a Tabela de Status de Adesão.

Consulta pelo código de notificação

A API de Notificações pode lhe enviar mensagens a cada mudança de status ocorrida em alguma recorrência.

Para consultar os dados da recorrência em questão, utilize o método /pre-approvals/notifications/{notificationCode} (veja a documentação).

URL: GET https://ws.pagseguro.uol.com.br/pre-approvals/notifications/{notificationCode}{autenticação}

O parâmetro {notificationCode} é o código da notificação recebida.

No retorno, o status da recorrência pode ser lido de acordo com a Tabela de Status de Adesão.

Consulta de notificações por intervalo de dias

A API de Notificações pode lhe enviar mensagens a cada mudança de status ocorrida em alguma recorrência.

Para consultar os dados de todas as recorrências que tiveram algum tipo de notificação dentro de um intervalo em dias, utilize o método /pre-approvals/notifications (veja a documentação).

URL: GET https://ws.pagseguro.uol.com.br/pre-approvals/notifications/{autenticação}

O retorno deste método pode ser paginado, verifique na referência da API os parâmetros de entrada.

No retorno, o status da recorrência pode ser lido de acordo com a Tabela de Status de Adesão.

Tabela de Status de Plano

Status Descrição
A Ativo. É possível fazer adesões
I Inativo. Não é possível fazer novas adesões até que ele seja reativado.
E Expirado. Não é possível mais utilizá-lo.

Tabela de Status de Adesão

Status Descrição
INITIATED O comprador iniciou o processo de pagamento, mas abandonou o checkout e não concluiu a compra.
PENDING O processo de pagamento foi concluído e transação está em análise ou aguardando a confirmação da operadora.
ACTIVE A criação da recorrência, transação validadora ou transação recorrente foi aprovada.
PAYMENT_METHOD_CHANGE Uma transação retornou como "Cartão Expirado, Cancelado ou Bloqueado" e o cartão da recorrência precisa ser substituído pelo comprador.
SUSPENDED A recorrência foi suspensa pelo vendedor.
CANCELLED A criação da recorrência foi cancelada pelo PagSeguro.
CANCELLED_BY_RECEIVER A recorrência foi cancelada a pedido do vendedor.
CANCELLED_BY_SENDER A recorrência foi cancelada a pedido do comprador.
EXPIRED A recorrência expirou por atingir a data limite da vigência ou por ter atingido o valor máximo de cobrança definido na cobrança do plano.

Tabela de Status de Ordem de Pagamento

Status Valor Descrição
1 Agendada A ordem de pagamento está aguardando a data agendada para processamento.
2 Processando A ordem de pagamento está sendo processada pelo sistema.
3 Não Processada A ordem de pagamento não pôde ser processada por alguma falha interna, a equipe do PagSeguro é notificada imediatamente assim que isso ocorre.
4 Suspensa A ordem de pagamento foi desconsiderada pois a recorrência estava suspensa na data agendada para processamento.
5 Paga A ordem de pagamento foi paga, ou seja, a última transação vinculada à ordem de pagamento foi paga.
6 Não Paga A ordem de pagamento não pôde ser paga, ou seja, nenhuma transação associada apresentou sucesso no pagamento.

Tabela de Status de Transação

Status Valor Descrição
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.
6 Devolvida O valor da transação foi devolvido para o comprador.
7 Cancelada A transação foi cancelada sem ter sido finalizada.

Tabela de Listagem de Erros

Código de erro Mensagem
10003 Email invalid value.
10005 The accounts of the vendor and buyer can not be related to each other.
10009 Method of payment currently unavailable.
10020 Invalid payment method.
10021 Error fetching vendor data from the system.
10023 Payment Method unavailable.
10024 Unregistered buyer is not allowed.
10025 senderName cannot be blank.
10026 senderEmail cannot be blank.
10049 senderName mandatory.
10050 senderEmail mandatory.
11002 receiverEmail invalid length: {0}
11006 redirectURL invalid length: {0}
11007 redirectURL invalid value: {0}
11008 reference invalid length: {0}
11013 senderAreaCode invalid value: {0}
11014 senderPhone invalid value: {0}
11027 Item quantity out of range: {0}
11028 Item amount is required. (e.g. "12.00")
11040 maxAge invalid pattern: {0}. Must be an integer.
11041 maxAge out of range: {0}
11042 maxUses invalid pattern: {0}. Must be an integer.
11043 maxUses out of range: {0}
11054 abandonURL/reviewURL invalid length: {0}
11055 abandonURL/reviewURL invalid value: {0}
11071 preApprovalInitialDate invalid value.
11072 preApprovalFinalDate invalid value.
11084 seller has no credit card payment option.
11101 preApproval data is required.
11163 You must configure a transactions notifications (Notificação de Transações) URL before using this service.
11211 pre-approval cannot be paid twice on the same day.
13005 initialDate must be lower than allowed limit.
13006 initialDate must not be older than 180 days.
13007 initialDate must be lower than or equal finalDate.
13008 search interval must be lower than or equal 30 days.
13009 finalDate must be lower than allowed limit.
13010 initialDate invalid format use 'yyyy-MM-ddTHH:mm' (eg. 2010-01-27T17:25).
13011 finalDate invalid format use 'yyyy-MM-ddTHH:mm' (eg. 2010-01-27T17:25).
13013 page invalid value.
13014 maxPageResults invalid value (must be between 1 and 1000).
13017 initialDate and finalDate are required on searching by interval.
13018 interval must be between 1 and 30.
13019 notification interval is required.
13020 page is greater than the total number of pages returned.
13023 Invalid minimum reference length (1-255)
13024 Invalid maximum reference length (1-255)
17008 pre-approval not found.
17022 invalid pre-approval status to execute the requested operation. Pre-approval status is {0}.
17023 seller has no credit card payment option.
17024 pre-approval is not allowed for this seller {0}
17032 invalid receiver for checkout: {0} verify receiver's account status and if it is a seller's account.
17033 preApproval.paymentMethod isn't {0} must be the same from pre-approval.
17035 Due days format is invalid: {0}.
17036 Due days value is invalid: {0}. Any value from 1 to 120 is allowed.
17037 Due days must be smaller than expiration days.
17038 Expiration days format is invalid: {0}.
17039 Expiration value is invalid: {0}. Any value from 1 to 120 is allowed.
17061 Plan not found.
17063 Hash is mandatory.
17065 Documents required.
17066 Invalid document quantity.
17067 Payment method type is mandatory.
17068 Payment method type is invalid.
17069 Phone is mandatory.
17070 Address is mandatory.
17071 Sender is mandatory.
17072 Payment method is mandatory.
17073 Credit card is mandatory.
17074 Credit card holder is mandatory.
17075 Credit card token is invalid.
17078 Expiration date reached.
17079 Use limit exceeded.
17080 Pre-approval is suspended.
17081 pre-approval payment order not found.
17082 invalid pre-approval payment order status to execute the requested operation. Pre-approval payment order status is {0}.
17083 Pre-approval is already {0}.
17093 Sender hash or IP is required.
17094 There can be no new subscriptions to an inactive plan.
19001 postalCode invalid Value: {0}
19002 addressStreet invalid length: {0}
19003 addressNumber invalid length: {0}
19004 addressComplement invalid length: {0}
19005 addressDistrict invalid length: {0}
19006 addressCity invalid length: {0}
19007 addressState invalid value: {0} must fit the pattern: \w{2} (e. g. "SP")
19008 addressCountry invalid length: {0}
19014 senderPhone invalid value: {0}
19015 addressCountry invalid pattern: {0}
50103 postal code can not be empty
50105 address number can not be empty
50106 address district can not be empty
50107 address country can not be empty
50108 address city can not be empty
50131 The IP address does not follow a valid pattern
50134 address street can not be empty
53037 credit card token is required.
53042 credit card holder name is required.
53047 credit card holder birthdate is required.
53048 credit card holder birthdate invalid value: {0}
53151 Discount value cannot be blank.
53152 Discount value out of range. For DISCOUNT_PERCENT type the value must be greater than or equal to 0.00 and less than or equal to 100.00.
53153 not found next payment for this preApproval.
53154 Status cannot be blank.
53155 Discount type is mandatory.
53156 Discount type invalid value. Valid values are: DISCOUNT_AMOUNT and DISCOUNT_PERCENT.
53157 Discount value out of range. For DISCOUNT_AMOUNT type the value must be greater than or equal to 0.00 and less than or equal to the maximum amount of the corresponding payment.
53158 Discount value is mandatory.
57038 address state is required.
61007 document type is required.
61008 document type is invalid: {0}
61009 document value is required.
61010 document value is invalid: {0}
61011 cpf is invalid: {0}
61012 cnpj is invalid: {0}