Fluxos de cobrança

Na seção anterior você teve uma boa introdução a diversos conceitos e mecanismos que fazem parte do funcionamento de nosso produto de recorrência, com eles você já consegue entender bastante coisa e utilizar nossas assinaturas sem medo.

Mesmo assim, criamos mais essa seção para dar firmada em todos essas ideias, e te ajudar a entender como realmente funciona a lógica por trás de nosso sistema. Então vamos lá!

Criando uma assinatura

Como você já viu nas seções anteriores, para criar uma assinatura tudo que você precisa é de um plano e das configurações corretas. Mas vamos dar uma olhada um pouco mais aprofundada na forma recomendada para você realizar esse processo e o que pode acontecer em cada etapa.

1. Criando o Plano

A primeira coisa que você precisa é criar um plano que atenda as necessidades de seu negócio. Para a maioria das integrações, o mais prático é criar todos os planos de antemão, ou seja, sabendo quais as necessidades de sua loja você pode criar inúmeros planos com configurações especificas para cada tipo de cliente em sua loja, com todos eles salvos, você só precisa relacionar seus ids (identificadores) com cada possibilidade de assinatura que seu site oferece.

Mas, para casos específicos também é possível fazer a criação de novos planos toda vez que sua aplicação for criar uma nova assinatura, já que em alguns modelos de negócios os valores e configurações da recorrência podem ser bastante variáveis.

Isso pode ser feito manualmente através de sua dashboard (para aplicações em pequena escala) ou de maneira integrada a seu site, onde os parâmetros da requisição de criação de plano são escolhidos dependendo dos inputs de seus clientes ou funcionários.

2. Criando o card_hash (Para assinaturas de cartão de crédito)

Em seguida, antes de criar sua assinatura, recomendamos que seja criado o card_hash que encripta todas as informações do cartão de seu cliente, e permite a comunicação segura desses dados sensíveis. Para isso você pode utilizar de nosso Checkout Pagar.me, as funções de nossos SDK’s ou então implementá-la diretamente em sua pagina seguindo nossa documentação em Obtendo os dados do Cartão.

3. Criando o card_id (Para assinaturas de cartão de crédito)

Com o card_hash em mãos você pode aproveitar e já criar um card_id para esse cartão, como explicado em Criando um cartão para one-click buy, isso permite que você crie assinaturas e transações com esse cartão sem se preocupar em ter que armazenar as informações brutas dos cartões de seus clientes, basta salvar em seu banco de dados esse card_id e enviá-lo dentro de suas requisições, substituindo as informações do cartão de crédito. Essa é uma ótima forma de padronizar suas requisições e permitir que seus clientes realizem transações em sua plataforma sem ter de introduzir as informações de pagamento novamente (one-click-buy).

4. Criando a assinatura

Agora sim! Com esses dados você já pode criar sua assinatura usando as recomendações e parâmetros apresentados anteriormente.

5. Verificando se tudo correu bem

Como ultimo passo após a criação da sua assinatura vale lembrar a importância de interpretar corretamente as informações contidas na resposta de nossa API, garantindo principalmente que informações como o status, o plan_id e os current_period_start e current_period_end estão de acordo com o esperado.

Sucessão dos Estados de uma assinatura

Com a sua assinatura criada e operante, há algumas coisas que você deve se atentar, a primeira delas sendo qual a sequência de status esperada.

Lembrando que isso irá afetar diretamente como o seu sistema irá receber nossos Postbacks e quando o seu cliente receberá seus E-mails de recorrência.

Conforme ilustrado no gráfico abaixo e documentado na seção Estados de uma assinatura, existem três possíveis estados iniciais e dois estados finais para uma assinatura.

Estados iniciais:

• O status trialing: É aplicado para todas as assinaturas criadas com um plano que possui o parâmetro trial_days preenchido.

• O status paid: Para assinaturas de cartão criadas sem trial_days. Como nossas assinaturas são criadas somente após a primeira cobrança ser realizada com sucesso, seu status inicial será paid sinalizando que ela já foi paga para seu primeiro período.

• O status unpaid: Para assinaturas de boleto criadas sem trial_days, já que temos que esperar o pagamento do primeiro boleto de uma assinatura para podermos considerá-la paga.

Estados finais (irreversíveis):

• O status ended: É aplicado para todas as assinaturas que cumpriram o número de cobranças estabelecido no parâmetro charges de seu plano vigente.

• O status canceled: Aplicado para todas as assinaturas que foram canceladas por você através de sua Dashboard ou pela rota da API Cancelando uma assinatura. Ou por seu cliente, através do botão de gerenciar assinatura presente em seus E-mails de recorrência. Ou ainda, caso a configuração de "Cancelar a assinatura após todas as cobranças" esteja habilitada, a assinatura irá automaticamente para o status canceled após todas as tentativas de cobrança realizadas nos status pending_payment e unpaid, saiba mais em Estados de uma assinatura.

Nesse meio tempo, entre os status iniciais e finais, o ideal seria uma sucessão de mudanças de status do tipo paid => paid. Onde seu cliente realiza todos os pagamentos referentes a sua assinatura dentro do prazo determinado, fazendo com que seu status (que estava previamente como paid) vá para paid, seu current_period_start e current_period_end sejam atualizados, e seja desencadeado o envio do postback e e-mail para informar da renovação.

Porém sabemos que muitas vezes não é isso que acontece, assim, temos os status pending_payment e unpaid, que servem como uma barreira entre o cliente e o cancelamento precipitado de sua assinatura.

Assim, quando um boleto não é pago ou o cartão vinculado a assinatura não permite a realização de uma cobrança, nosso sistema faz a atualização da assinatura para o status pending_payment, onde o usuário ainda terá acesso aos serviços da assinatura mas será cobrado todos os dias durante o período de tolerância.

Caso seja uma assinatura de cartão, essa cobrança se dá na forma de uma nova tentativa de criação de transação no cartão cadastrado acompanhada de um e-mail informando se essa cobrança foi bem-sucedida ou não. Para voltar ao status paid, o usuário ainda tem a opção de realizar uma troca do cartão de crédito vinculado, ou do método de pagamento (caso o plano permita), através do botão de gerenciar assinatura presente em seus e-mails.

Caso seja uma assinatura de boleto, essa cobrança inclui somente o e-mail informando da falta de pagamento do ultimo boleto gerado.

Se a assinatura é paga dentro do prazo de tolerância (do status pending_payment), ela então segue as datas previamente estabelecidas do current_period_start e current_period_end e a próxima cobrança pode ocorrer normalmente, como se a assinatura nunca tivesse entrado no status pending_payment.

Porém caso não seja detectado nenhum pagamento ao fim do período de tolerância, a assinatura vai para o status de inadimplência unpaid, onde o usuário não deve ter mais acesso aos serviços da assinatura e será cobrado seguindo as suas configurações de recorrência.

Este inclusive pode ser o status final de sua assinatura, caso a configuração de "Cancelar a assinatura após todas as cobranças" esteja desabilitada, a assinatura continuará no status unpaid indefinidamente.

Porém não consideramos o status unpaid como um dos status finais de uma assinatura, pois ele não é irreversível, mesmo que uma assinatura fique no status unpaid por bastante tempo ela ainda pode ser reativada com um novo pagamento de cobrança.

Se a assinatura é paga quando está unpaid, um novo ciclo se inicia no dia desse pagamento, como se a assinatura estivesse sendo reiniciada. Por esse motivo, aconselhamos o corte do serviço assim que uma assinatura entra no status unpaid.

No status unpaid o usuário também tem a opção de realizar uma troca de seu cartão de crédito vinculado ou o método de pagamento (caso o plano permita), como no status pending_payment. Inclusive essa seria a maneira recomendada de reiniciar uma assinatura que já passou por todos as tentativas de cobrança do período de inadimplência, já que, para os staus pending_payment e unpaid, após qualquer alteração feita pelo usuário, iremos tentar realizar uma nova cobrança na assinatura.

Por fim, vale lembrar que, a qualquer momento nesses dois status intermediários (pending_payment e unpaid), você pode dar baixa na cobrança vigente de uma assinatura. Como mostrado na seção Pulando cobranças de uma assinatura, ao realizar esse procedimento você estará efetivamente fazendo nosso sistema interpretar que houve o pagamento da ultima cobrança, alterando o status da assinatura para paid e permitindo uma continuidade normal das cobranças.

Mais informações sobre os detalhes de cada um desses status e como eles afetam suas assinaturas nas seções Estados de uma assinatura.

Atualizando o plano de uma assinatura

Caso você deseje alterar o valor ou qualquer outra configuração definida pelos parâmetros do plano de sua assinatura, você pode utilizar de nossa rota de API Atualizando uma assinatura, passando um id de assinatura e um novo id de plano, nosso sistema irá fazer a troca de planos e isso irá afetar todas as próximas cobranças de sua assinatura.

curl -X PUT https://api.pagar.me/1/subscriptions/subscription_id -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY",  
    "plan_id": "166234"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id(subscription_id)

subscription.plan_id = '166234'

subscription.save

<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$updatedSubscription = $pagarme->subscriptions()->update([
  'id' => subscription_id,
  'plan_id' => 166234
]);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var subscription = PagarMeService.GetDefaultService().Subscriptions.Find("subscription_id");

subscription.Plan = PagarMeService.GetDefaultService().Plans.Find(166234);
subscription.Save();

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.update({ 
  id: 'subscription_id',
  plan_id: '166234'          
  }))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.update(
    "subscription_id",
    {
        "plan_id": "166234"
    }
)

print (subscription)

Além disso, nós iremos alterar o parâmetro de cobranças realizadas (charges) para zero, pois consideramos que, por se tratar de um plano novo a configuração de cobranças dele deve ser respeitada.

Para nosso sistema todas as alterações de plano são classificadas em dois fluxos, Downgrade e Upgrade. Onde o downgrade cobre alterações onde o valor (amount) do plano novo é igual ou menor que o do plano antigo, e o upgrade cobre as alterações onde ele é maior. Além disso, vale ressaltar que quando o plano novo possui período de trial (trial_days) esses fluxos são levemente alterados, para saber mais você pode consultar a nossa seção Atualizações para planos com trial_days.

Downgrade

Cartão de crédito

1. No caso de assinaturas de cartão, a primeira coisa que iremos fazer ao receber sua requisição de atualização de plano, é verificar o status dessa assinatura.

   1.1. Caso ela esteja no status paid nós não iremos gerar uma nova cobrança, e somente sua periodicidade será alterada. Após o downgrade, essa assinatura irá manter seu status como paid permitindo que seu usuário mantenha seu acesso ininterruptamente.

   1.2. Para o caso dela estar em qualquer outro status, exceto os status finais, ou seja para assinaturas nos status trialing, pending_payment ou unpaid, iremos gerar uma nova cobrança no valor do plano novo, ela será preenchida no current_transaction e em seguida faremos a alteração de sua periodicidade.

Caso a cobrança no cartão do usuário seja mal sucedida (transação recusada) o processo de downgrade será interrompido e ela será mantida no plano antigo.

2. O current_period_start da assinatura passa a ser a data atual.

3. O current_period_end do novo período é calculado da seguinte maneira:

   3.1. Se a opção "Considerar valor do plano em downgrades" estiver habilitada, o fórmula utilizada é essa:

   Primeiro descobrimos o valor referente ao tempo não utilizado pelo cliente no plano antigo.

Onde dias restantes do plano antigo representam o número de dias que faltam para o fim do período (current_period_end) logo antes de ser realizado o downgrade.

Após isso, precisamos saber qual o valor diário do novo plano.

E por fim, calculamos quantos dias serão adicionados até a próxima cobrança de acordo com o valor restante do plano antigo dividido pelo valor diário do plano novo.

Assim, alcançamos o current_period_end desejado:

3.2. Se a opção "Considerar valor do plano em downgrades" estiver desabilitada, a fórmula utilizada é essa:

É obtida a proporção não usufruída do plano.

Onde os dias restantes do plano antigo são o número de dias que faltam para chegar no current_period_end da assinatura.

Essa proporção é multiplicada pelo número de dias do plano novo, e o current_period_end da assinatura passa a ser esse número de dias, a partir da data atual.

Nesse cálculo, a proporção é feita apenas pela quantidade de dias, e o valor dos planos não é utilizado.

Isso ocorre para que o tempo mais caro que já foi pago não seja "perdido" pelo cliente. O cliente só volta a ser cobrado depois que a proporção de dias do plano mais caro já tiver sido usufruída, mesmo que no plano mais barato.

4. Assim, com o current_transaction e o current_period_end atualizados, o processo de downgrade se finaliza, nós salvamos o novo plan_id na assinatura e ela está pronta para seguir com o fluxo de cobranças esperado.

Boleto

1. No caso de assinaturas de boleto, iremos primeiro verificar o valor do plano novo.

   1.1. Se ele for igual ao valor do plano antigo, nós não iremos gerar uma nova cobrança, já que o usuário pode realizar o pagamento do boleto já gerado anteriormente para seguir com sua assinatura.

   1.2. Já no caso do valor ser menor que o do plano antigo, nós iremos gerar uma nova cobrança no valor do plano novo, pois assim será gerado um novo boleto com o valor correto para essa assinatura. Essa cobrança será preenchida no current_transaction, e terá 7 dias como prazo de validade.

2. Em seguida iremos verificar como será a alteração do status dessa assinatura:

   2.1. Caso a assinatura esteja nos status trialing, pending_payment ou unpaid ela irá para o status unpaid após o downgrade.

   E o current_period_start e o current_period_end serão alterados para null já que o novo período só irá começar após o pagamento do boleto gerado.

   2.2. Caso a assinatura esteja no status paid, iremos manter esse status após o downgrade para não prejudicar o acesso do usuário.

   Em seguida o current_period_start e o current_period_end da assinatura são alterados da mesma forma que foi descrita na seção anterior para Downgrade de cartão de crédito.

3. Assim, com o current_transaction e o current_period_end atualizados, o processo de downgrade se finaliza, nós salvamos o novo plan_id na assinatura e ela está pronta para seguir com o fluxo de cobranças esperado.

Upgrade

Cartão de crédito

1. No upgrade de assinaturas de cartão acontece uma nova cobrança, que é calculada da seguinte maneira:

   1.1. Se o status da assinatura não for paid, ou seja, caso ela esteja nos status trialing, pending_payment ou unpaid, uma cobrança com o valor do novo plano é feita.

   1.2. Se o status da assinatura for paid, é feita a seguinte conta:

   É obtido o valor não usufruído do plano antigo multiplicando a proporção não usufruída pelo valor do plano antigo:

Onde os dias restantes do plano antigo são o número de dias que faltam para chegar no current_period_end da assinatura.

É subtraído o valor não usufruído do valor do plano novo, e esse resultado é cobrado.

Caso a cobrança no cartão do usuário seja mal sucedida (transação recusada) o processo de upgrade será interrompido e ela será mantida no plano antigo.

2. Uma transação é criada com esse valor e o current_period_start é alterado para a data do upgrade e o current_period_end é alterado para:

Isso ocorre para não cobrarmos o valor não usado do plano antigo no plano novo.

3. Assim, com o current_transaction e o current_period_end atualizados, o processo de upgrade se finaliza, nós salvamos o novo plan_id na assinatura e ela está pronta para seguir com o fluxo de cobranças esperado.

Boleto

1. No upgrade de assinaturas de boleto acontece uma nova cobrança no valor do plano novo.

   1.1. Se o status da assinatura não for paid, ou seja, caso ela esteja nos status trialing, pending_payment ou unpaid, o status da assinatura vai para unpaid.

   E o current_period_start e o current_period_end serão alterados para null já que o novo período só irá começar após o pagamento do boleto gerado.

   1.2. Se o status da assinatura for paid, iremos manter esse status após o upgrade para não prejudicar o acesso do usuário. Porém, já que não temos como saber quando será feito o pagamento do novo boleto gerado, não podemos descontar o valor não usufruído do plano antigo do valor deste boleto, como no upgrade com cartão.

Assim, nós realizamos a conversão desse valor em dias adicionais para o plano novo, alterando a periodicidade da assinatura da seguinte forma:

2. O current_period_start da assinatura passa a ser a data atual.

3. O current_period_end do novo período é calculado da seguinte maneira:

   3.1. Primeiro descobrimos o valor referente ao tempo não utilizado pelo cliente no plano antigo.

Onde dias restantes do plano antigo representam o número de dias que faltam para o fim do período (current_period_end) logo antes de ser realizado o upgrade.

Após isso, precisamos saber qual o valor diário do novo plano.

E por fim, calculamos quantos dias serão adicionados ao fim do período atual usando o valor restante do plano antigo dividido pelo valor diário do novo plano.

E alcançamos o current_period_end desejado:

4. Assim, com o current_transaction e o current_period_end atualizados, o processo de upgrade se finaliza, nós salvamos o novo plan_id na assinatura e ela está pronta para seguir com o fluxo de cobranças esperado.

Atualizações para planos com trial_days

Caso o plano que você deseja para sua assinatura possua dias de trial configurados nele, algumas coisas a mais devem ser consideradas.

De forma geral iremos tratar essa mudança de planos como se fosse uma nova assinatura criada com dias de trial. Após receber a requisição de atualização de plano, não iremos gerar uma nova cobrança, somente iremos mudar o status da assinatura para trialing, o Current_period_start para a data da atualização do plano e o Current_period_end para ser igual ao Current_period_start acrecido do período de trial do plano novo.

Não iremos fazer nenhum cálculo de desconto ou acréscimo de dias para a cobrança do fim do trial, ou seja, quando esse período acabar, a cobrança gerada terá o valor cheio do plano novo, o Current_period_start será o dia do final do trial e o Current_period_end será igual ao dia do final do trial acrecido do período do plano novo.

Por fim, vale ressaltar mais um caso, se a assinatura no plano antigo também estava em seu período de trial, nós iremos calcular a diferença entre esses períodos para determinar o status da assinatura.

Primeiramente iremos calcular o número de dias utilizados no período de trial do plano antigo:

Com isso nós verificamos se o período de trial do plano novo é maior que os dias utilizados de trial do plano antigo. Caso seja, nós definimos o Current_period_end da seguinte forma:

Basicamente, descontando os dias de trial já utilizados no plano antigo do período de trial do plano novo.

E caso contrário, quando os dias de trial utilizados no plano antigo são maiores que o período de trial do plano novo, nós entendemos que o usuário já usufruiu do período de trial desejado para ele, e assim, nós ignoramos esse período no plano novo e seguimos os fluxos de upgrade e downgrade conforme estabelecidos anteriormente.