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

Funcionalidades

Nesta documentação você verá os seguintes itens:

Máquina de Status das Adesões
Regras para Criação de Planos
Regras de Expiração de Plano e Adesão
Regras de Cobrança
Regras de Cancelamento da Adesão
Edição de Valor em Planos
Mudança de Meio de Pagamento

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.

1528

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 do 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 do 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 em Tabelas de Status e Erros.

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

1181

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).

🚧

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

920

Exemplo 2:

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

1105

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

🚧

O pagSeguro poderá efetuar transação validadora (no valor de R$ 1,50) apenas para verificar a validade do cartão.

É 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).

1528

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ão.

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 e Planos

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.