Conceitos de recorrência

Agora que você já sabe criar planos e assinaturas, é importante entender o ciclo de vida, os meios de cobrança e os possíveis cenários que a recorrência pode assumir. Dessa forma, você pode tomar melhores decisões de acordo com a necessidade do seu negócio. Vamos lá!

Periodicidade de uma assinatura

Toda assinatura tem um current_period_start e um current_period_end, indicando, respectivamente, o início e o fim do período de cobrança atual.

Dessa forma, para uma assinatura recém-gerada com um plano de 30 dias sem trial, o current_period_start é o dia da criação da assinatura, e o current_period_end é definido como 30 dias após o current_period_start.

As cobranças serão sempre realizadas na data do current_period_end, e a última transação realizada dentro de uma assinatura está disponível no parâmetro current_transaction.

É importante notar que, em assinaturas pagas usando boleto, o current_transaction representa a próxima cobrança, a que já está disponível mas ainda será paga pelo assinante. Já para cartão de crédito, o current_transaction representa a última transação, paga ou recusada, do período atual.

Perceba então que para assinaturas por boleto o objeto current_transaction possui uma transação com status waiting_payment. Pois o Pagar.me gera um novo boleto assim que o último é pago.

No entanto, para cartão de crédito o retorno dentro de current_transaction será sempre a última transação realizada no cartão do portador, com os possíveis status: paid ou refused.

Estados de uma assinatura

Estes são todos os estados (ou status) de nossas assinaturas, cada um deles tem suas próprias características que podem ser utilizadas para facilitar a gestão de seu negócio.

Paid: A assinatura está paga e em dia.
Trialing: A assinatura ainda está em período de testes e não foi realizada nenhuma cobrança.
Pending_payment: A assinatura ainda não foi paga, porém não ultrapassou o limite de dias de tolerância.
Unpaid: Quando o pagamento não foi efetuado e o prazo de tolerância foi esgotado.
Ended: Quando a assinatura concluiu todos as cobranças definidas pelo plano.
Canceled: Quando a assinatura foi cancelada antes do final do seu período.

E a seguir uma descrição mais detalhada dos status e as possíveis funções que podem ser utilizadas em cada um deles para pagamento com cartão de crédito e boleto:

Cartão de crédito

1. Paid

Ao criar uma assinatura de cartão de crédito sem período de trial, tentamos na mesma hora realizar a primeira cobrança no cartão do usuário. A assinatura passa a ter o status paid caso a cobrança ocorra com sucesso. Caso essa primeira cobrança ou a validação do cartão de crédito falhe, a assinatura não é criada e um erro indicando que não foi possivel criar uma transação nesse cartão é retornado.

Após a primeira cobrança, toda vez que uma assinatura chega no current_period_end (data do final do período atual) uma nova tentativa de cobrança é realizada, para isso iremos pegar as informações do cartão de crédito e do assinante e tentaremos criar uma nova transação para a assinatura, caso ela seja bem sucedida alteramos o status da assinatura para paid, o current_period_start para a data da cobrança e o current_period_end para a data prevista para a próxima cobrança. Caso ela não seja bem sucedida, nós alteramos o status da assinatura para pending_payment, e começamos o fluxo de cobranças do prazo de tolerância. Você pode ver mais informações sobre os fluxos de sua assinatura na seção Fluxos de cobrança.

2. Trialing

Se o plano tiver um período de trial, iremos validar o cartão antes de armazená-lo, mas a primeira cobrança só será realizada ao final do trial, marcado como o current_period_end (data do final do período atual). Até lá, a assinatura terá o status trialing.

Caso esse cartão não seja considerado valido, a assinatura não é criada e um erro é retornado.

3. Pending_payment

Quando a assinatura atinge o fim do período atual sem ser paga, ela muda para o status pending_payment. Durante esse status, tentamos cobrar o usuário todos os dias e também o notificamos por e-mail caso o pagamento seja bem sucedido, falhe ou não seja detectado. Além disso, mandamos nesse e-mail um link para uma página onde ele pode alterar a forma de pagamento, trocar o cartão de crédito utilizado ou mesmo cancelar a assinatura.

Por padrão, o período em que a assinatura fica com status pending_payment é de cinco dias. Esse valor do prazo de tolerância pode ser configurado pela Dashboard. Saiba mais em: Configurações de recorrência.

Se após o prazo de tolerância, onde a assinatura fica no status pending_payment, ela mesmo assim não for paga, iremos alterar o status da assinatura para unpaid.

4. Unpaid

Quando a assinatura atinge o status unpaid, você pode então cortar o acesso do usuário ao seu serviço/sistema, já que ele encontra-se inadimplente. Isso acontece depois que o prazo de tolerância é finalizado e é bastante recomendado.

Durante o status unpaid, por padrão são feitas mais quatro tentativas de cobrança com um intervalo de três dias entre elas. Tanto o número de tentativas quanto o intervalo entre elas podem ser configuradas pela sua Dashboard, e são únicos para a sua conta. Isto é, não é possível ter valores diferentes para planos diferentes. Saiba mais em: Configurações de recorrência.

Você pode optar por cancelar automaticamente a assinatura depois desse período. Isto é, depois de todas as tentativas de cobrança dos status pending_payment e unpaid, iremos alterar o status da assinatura para canceled onde ela não poderá sofrer novas alterações. Essa opção pode ser configurada pela sua Dashboard e por padrão está desabilitada. Saiba mais em: Configurações de recorrência.

A outra opção é apenas cortar o acesso ao serviço/sistema, mas manter a assinatura como unpaid indefinidamente. Dessa forma, se o usuário quiser voltar a usar a conta, você pode negociar diretamente com ele o pagamento e então reativar o acesso.

5. Ended

Se a assinatura realizar todas as cobranças que foram definidas no parâmetro charges de seu plano, quando ela chegar no fim de seu ultimo período, ao invés de ser criada uma nova transação, iremos alterar seu status para ended. A partir desse momento, ela não poderá ser modificada e não iremos gerar novas cobranças.

Caso deseje continuar com uma assinatura que alcançou o status ended recomendamos que crie uma nova assinatura para seu cliente.

6. Canceled

Após o cancelamento, nenhuma tentativa extra de cobrança é feita. Uma assinatura cancelada não pode ser alterada nem cobrada novamente, então se o assinante quiser voltar a usar o seu serviço, ele precisa criar uma nova assinatura. Você pode realizar esse procedimento a qualquer momento através da rota Cancelando uma assinatura.

Outros cenários que levam ao cancelamento de uma assinatura são, o fim das tentativas automáticas de cobrança dos status pending_payment e unpaid, contanto que essa configuração esteja ativa em sua Dashboard, e o recebimento de um pedido de chargeback em alguma das transações atreladas àquela assinatura, já que entendemos que, se o assinante pediu um chargeback de alguma cobrança ele não deseja mais fazer parte daquela assinatura.

Boleto

1. Paid

Ao criar uma assinatura de boleto bancário, um boleto é emitido com um certo número de dias de validade, o padrão sendo 7, esse valor pode ser definido através do parâmetro boleto_expiration_date na requisição de criação de assinatura, ou pode ser configurado para sua conta como um todo na aba Boletos de sua Dashboard.

A assinatura fica com status unpaid até que o boleto bancário seja pago. Ao detectarmos o pagamento, o status muda para paid, e já emitimos o próximo boleto da assinatura, ele terá validade até a data do current_period_end (final do período atual), permitindo assim que seu cliente tenha o máximo de tempo possível para realizar o pagamento de seus boletos.

Dessa forma permitimos que o assinante realize o pagamento do boleto na hora que desejar, podendo inclusive realizar o pagamento de mais de uma cobranças em sequência. Assim, nosso sistema interpreta cada pagamento conforme eles são realizados, e logo que recebemos a confirmação de pagamento do banco já alteramos o status da assinatura para paid, o current_period_end para a data prevista para a próxima cobrança e geramos o próximo boleto com data de validade igual a esse novo current_period_end.

Por isso, toda vez que uma assinatura de boleto alcança seu current_period_end nós alteramos seu status para pending_payment e começamos o fluxo de cobranças do prazo de tolerância.

2. Trialing

Se o plano tiver um período de trial, o boleto continua sendo emitido no momento da criação da assinatura, porém com data de validade para o fim do período de trial.

Durante esse período a assinatura fica com status trialing. Se, nesse meio tempo o boleto for pago, a assinatura então muda para o status paid, e o período do plano é acrescentado ao current_period_end. E caso o boleto não tenha sido pago até o fim do trial, o status da assinatura passa para unpaid.

3. Pending_payment

Quando a assinatura atinge o fim do período atual sem ser paga, ela muda para o status pending_payment. Durante esse status, notificamos o usuário por e-mail todos os dias, informando que o pagamento do boleto não foi detectado. Além disso, mandamos por e-mail um link para uma página onde ele pode visualizar o boleto, alterar a forma de pagamento ou mesmo cancelar a assinatura.

Se após esse prazo de tolerância, a assinatura mesmo assim não for paga, iremos alterar o status dela para unpaid.

4. Unpaid

Toda assinatura de boleto sem período de trial é criada no status unpaid, já que não foi realizado o pagamento do primeiro boleto (gerado com a criação da assinatura), e portanto entendemos que o usuário ainda não deve ter acesso ao serviço/sistema oferecido, após o pagamento deste boleto a assinatura vai para paid e o fluxo segue de maneira semelhante às assinaturas de cartão.

Quando a assinatura atinge o status unpaid novamente, o acesso do usuário deve ser cortado, já que ele se encontra inadimplente. Isso acontece depois que o prazo de tolerância é finalizado e é bastante recomendado.

Durante o status unpaid, por padrão são feitas mais quatro tentativas de cobrança, onde enviamos um e-mail para o usuário, informando sobre o estado de sua assinatura, essas tentativas são espaçadas, com um intervalo padrão de três dias entre elas. Tanto o número de tentativas quanto o intervalo entre elas podem ser configuradas pela sua Dashboard, e são únicos para a sua conta. Isto é, não é possível ter valores diferentes para planos diferentes. Saiba mais em: Configurações de recorrência.

Você pode optar por cancelar automaticamente a assinatura depois desse período. Ou seja, depois de todas as tentativas de cobrança dos status pending_payment e unpaid, iremos alterar o status da assinatura para canceled onde ela não poderá sofrer novas alterações. Essa opção pode ser configurada pelo seu Dashboard e por padrão está desabilitada. Saiba mais em: Configurações de recorrência.

5. Ended

Analogamente às assinaturas de cartão de crédito, se a assinatura realizar todas as cobranças que foram definidas no parâmetro charges de seu plano, quando ela chegar no fim de seu ultimo período, ao invés de ser criada uma nova transação, iremos alterar seu status para ended. A partir desse momento, ela não poderá ser modificada e não iremos gerar novas cobranças.

Caso deseje continuar com uma assinatura que alcançou o status ended recomendamos que crie uma nova assinatura para seu cliente.

6. Canceled

Também de forma análoga às assinaturas de cartão de crédito, uma assinatura cancelada não pode ser alterada nem cobrada novamente, então se o assinante quiser voltar a usar o seu serviço, ele precisa criar uma nova assinatura. Você pode realizar esse procedimento a qualquer momento através da rota Cancelando uma assinatura.

Outros cenários que levam ao cancelamento de uma assinatura são, o fim das tentativas automáticas de cobrança dos status pending_payment e unpaid, contanto que essa configuração esteja ativa em sua Dashboard, e o recebimento de um pedido de chargeback em alguma das transações atreladas àquela assinatura, já que entendemos que, se o assinante pediu um chageback de alguma cobrança ele não deseja mais fazer parte daquela assinatura.

Configurações de recorrência

Para definir configurações de cobrança, envio de e-mails e postback de assinaturas, basta acessar a página de sua Dashboard em Ver minha conta > Recorrência.

Os primeiros campos definem o comportamento de retentativas de cobrança da assinatura em caso de recusa/não pagamento de uma transação. Segue um exemplo considerando a primeira recusa no dia 4:

Prazo de tolerância: Define por quantos dias seguidos vamos tentar cobrar o assinante. Esse valor é único para sua conta, ou seja, não é possível ter prazos de tolerância diferentes para planos diferentes.
Número de tentativas de cobrança: Define quantas cobranças ainda serão realizadas depois que o prazo de tolerância acabar.
Intervalo entre cada cobrança: Define o intervalo de dias entre cada tentativa de cobrança, ao fim do período do prazo de tolerância.

No exemplo da imagem acima, a retentativa cobrança é feita por 5 dias seguidos e depois desse período, caso a recusa continue acontecendo, são realizadas mais 4 tentativas de cobrança com um intervalo de 3 dias entre elas.

Depois de definir as configurações de cobrança das assinaturas, apresentamos mais algumas opções:

Enviar e-mail para os clientes: Aqui é definido se nossa API irá enviar os e-mails referentes às alterações e cobranças de suas assinaturas ao assinante.
Cancelar a assinatura após todas as cobranças: Configura o cancelamento de uma assinatura em caso de não pagamento até o fim das tentativas de cobrança. Marcando-o como Não, as assinaturas continuarão no status unpaid e terão renovação automática caso haja novo pagamento.
Considerar valor do plano em downgrades: Essa configuração é para a atualização de assinaturas e define se você quer considerar o valor do plano mais caro, na hora de criar a nova transação atrelada a um plano mais barato. Se marcar Não, a proporção será feita considerando apenas o número de dias utilizados pelo cliente. Mais detalhes na seção Downgrade.

E-mails de recorrência

Como já mencionamos em algumas seções, nosso produto de recorrência vem com um sistema de envio de e-mails aos assinantes, essa é uma das razões para o parâmetro e-mail ser informação obrigatória do comprador na hora de se criar uma assinatura. Mas do que realmente se tratam esses e-mails?

Eles são uma forma de simplificar a integração de seu sistema com as funções que o mercado espera de uma loja que trabalha com assinaturas. Ao comprar um acesso ou serviço baseado em cobranças recorrentes, a maior parte dos consumidores deseja ter o maior controle possível sobre esse gasto, além de velocidade e consistência no recebimento de qualquer informação ou atualização relevante.

Assim, nosso sistema é baseado na lógica de que, enquanto a assinatura estiver em funcionamento, nós iremos enviar um e-mail para o seu cliente, informando-o sobre quaisquer mudanças na assinatura, pendência de pagamento, troca de plano e até o eventual cancelamento da mesma.

Abaixo você pode ver um exemplo de nosso e-mail informando o comprador de um pagamento bem-sucedido de sua assinatura.

Mas é claro que os e-mail para a sua loja não precisam ser iguais a esse, em sua Dashboard você pode acessar a página Ver minha conta > Configurações > Emails onde você pode personalizar o layout e as informações que vão em cada um de seus e-mails. Lá você verá as opções referentes sobre cada tipo de e-mail que enviamos, além de acesso ao código-fonte que define a aparência geral de nossos e-mails, permitindo uma grande personalização das disposições, informações e designs contidos neles.

Por padrão, todos nossos e-mails de recorrência também incluem um botão de gerenciar assinatura, que direciona o comprador para uma página onde ele pode visualizar todas as informações relevantes sobre sua assinatura, além de poder atualizar suas informações de cartão de crédito, trocar o método de pagamento (se o plano permitir) e até cancelar a assinatura. E, caso essas funções já estejam integradas em seu sistema, é possível desabilitar esse botão, alterando o layout de seus e-mails.

Por fim, como apresentado na seção anterior Configurações de recorrência, você pode desabilitar o envio de todos os e-mails de recorrência para sua conta a hora que desejar.