Bem-vindo à documentação pagar.me

Aqui você vai encontrar guias e exemplos para te ajudar
a integrar com a melhor API de Pagamentos do Brasil!

Começar

Você também pode buscar ou navegar pelas categorias

Fluxo de cobrança

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 decisões melhores de acordo com a necessidade do seu negócio. Vamos lá!

1. 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 com um plano de 30 dias que for criada hoje, o current_period_start é hoje, e o current_period_end é daqui a 30 dias.

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 na variável current_transaction. É importante notar que, em assinaturas pagas usando boleto, o current_transaction representa a próxima cobrança, a que 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.

Exemplo de retorno que contém o current_transaction:

{
  "object": "subscription",
  "plan": {
    "object": "plan",
    "id": 166232,
    "amount": 20000,
    "days": 30,
    "name": "The Gold Plan",
    "trial_days": 0,
    "date_created": "2017-06-19T11:55:38.725Z",
    "payment_methods": [
      "boleto",
      "credit_card"
    ],
    "color": null,
    "charges": null,
    "installments": 1,
    "invoice_reminder": null
  },
  "id": 208244,
  "current_transaction": {
    "object": "transaction",
    "status": "waiting_payment",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": null,
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": null,
    "soft_descriptor": null,
    "tid": 1662052,
    "nsu": 1662052,
    "date_created": "2017-06-28T13:11:48.057Z",
    "date_updated": "2017-06-28T13:11:48.279Z",
    "amount": 20000,
    "authorized_amount": 20000,
    "paid_amount": 0,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1662052,
    "cost": 0,
    "card_holder_name": null,
    "card_last_digits": null,
    "card_first_digits": null,
    "card_brand": null,
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "boleto",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": "https://pagar.me",
    "boleto_barcode": "1234 5678",
    "boleto_expiration_date": "2017-07-28T13:11:48.051Z",
    "referer": null,
    "ip": null,
    "subscription_id": 208244,
    "split_rules": null,
    "metadata": {
      "contrato_id": "420221"
    },
    "antifraud_metadata": {}
  },
  "postback_url": "https://requestb.in/1ll1psu1",
  "payment_method": "boleto",
  "card_brand": null,
  "card_last_digits": null,
  "current_period_start": "2017-06-28T13:11:48.046Z",
  "current_period_end": "2017-07-28T13:11:48.051Z",
  "charges": 1,
  "status": "paid",
  "date_created": "2017-06-28T13:08:23.235Z",
  "phone": {
    "object": "phone",
    "ddi": "55",
    "ddd": "614",
    "number": "33404556",
    "id": 23325
  },
  "address": {
    "object": "address",
    "street": "Rua da Consolação",
    "complementary": "The block 2 on the corner",
    "street_number": "34",
    "neighborhood": "Mini New England",
    "city": "Foz do Iguaçu",
    "state": "PR",
    "zipcode": "85870820",
    "country": "Brasil",
    "id": 24487
  },
  "customer": {
    "object": "customer",
    "id": 53280,
    "external_id": null,
    "type": null,
    "country": null,
    "document_number": "22222222222",
    "document_type": "cpf",
    "name": "Mr. John Smith",
    "email": "[email protected]",
    "phones": null,
    "born_at": null,
    "birthday": null,
    "gender": null,
    "date_created": "2016-04-07T16:45:19.043Z",
    "documents": []
  },
  "card": null,
  "metadata": {
    "produto_id": "420221"
  },
  "settled_charges": null
}

Perceba que o objeto current_transaction possui uma transação com status waiting_payment. Esse comportamento é normal para assinaturas por boleto, pois a API Pagar.me gera um novo boleto assim que o último é pago.

Conforme explicado anteriormente, 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.

1. Fluxo de criação de assinaturas

1.1 Cartão de crédito

Ao criar uma assinatura de cartão de crédito, 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. Entretanto, caso a primeira cobrança ou a validação do cartão de crédito falhe, a assinatura não é criada e um erro é retornado.

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

1.2 Boleto

Ao criar uma assinatura de boleto bancário, um boleto é emitido com 7 dias de validade. A assinatura fica com status unpaid até que o boleto bancário seja pago. Ao detectarmos o pagamento, o status muda para paid.

Se o plano tiver um período de trial, o boleto é emitido com data de validade para o fim do período de trial e a assinatura fica com status trialing. Ao fim do trial, se o boleto for pago, a assinatura então muda para o status paid.

Caso o boleto não tenha sido pago até o fim do trial, a assinatura passa para unpaid.

Lembrete de boletos

Na criação dos seus planos, você pode especificar um parâmetro chamado invoice_reminder, que aceita um número inteiro. Esse número determina em até quantos dias o seu assinante é lembrado de um boleto que esteja prestes a vencer. Saiba mais em: Criando Planos

2. Fluxo de cobrança ao final do período

2.1 Cartão de crédito

Ao fim de um período (current_period_end), o nosso sistema realiza a próxima cobrança na assinatura. Se o pagamento é feito com sucesso, a assinatura permanece com o status paid. Além disso, o current_period_start e current_period_end são atualizados conforme o valor definido em days de seu plano.

Caso a cobrança falhe por algum motivo (falta de saldo, transação negada pelo banco, etc), a assinatura entra no status pending_payment e o usuário é notificado por e-mail.

2.2 Boleto

Sempre que um boleto de uma assinatura é pago, o próximo boleto é emitido e já fica disponível para pagamento. Dessa forma, após o pagamento mais recente, o boleto correspondente ao próximo período já pode ser pago pelo cliente.

Quando é detectado o pagamento do boleto do próximo período, a assinatura continua com o status paid, e o current_period_start e current_period_end são atualizados. Dessa forma, se o usuário efetuar o pagamento antes do fim do período atual, o current_period_end tem um acréscimo proporcional a quantidade de dias que o pagamento foi adiantado.

Caso o boleto não seja pago até o fim do período, a assinatura entra no status pending_payment e o usuário é notificado por e-mail.

3. Prazo de tolerância após fim do período atual

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 falhe ou não seja detectado. Além disso, mandamos por e-mail um link para uma página onde ele pode alterar a forma de pagamento ou o cartão de crédito utilizado na assinatura.

Por padrão, o período em que a assinatura fica com status pending_payment é de cinco dias. Esse valor (payment_deadline) pode ser configurado pela Dashboard e é único para sua conta. Ou seja, não é possível ter deadlines diferentes para planos diferentes. Saiba mais em: Configurações de recorrência

Após os cinco dias de tentativas de cobrança, se a assinatura mesmo assim não for paga, ela então passa a ter o status unpaid.

4. Inadimplência - status 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, são feitas mais quatro tentativas de cobrança com um intervalo de três dias (por padrão) 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.

Você pode optar por cancelar automaticamente a assinatura depois desse período. Isto é, depois que todas as tentativas de cobrança — do status pending_payment e unpaid — forem realizadas sem sucesso. Essa opção pode ser configurada pelo seu Dashboard e por padrão está desabilitada.

A outra opção é apenas cortar o acesso ao serviço/sistema, mas manter a assinatura. 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.

Pagamentos atrasados

Se a assinatura é paga dentro do prazo de tolerância (pending_payment), ela então segue as datas normais dos ciclos e a próxima cobrança ocorre normalmente, como se a assinatura nunca tivesse entrado no estado pending_payment.

No entanto, se a assinatura é paga quando já está no estado unpaid, o assinante "ganha" esses dias nos quais ficou inadimplente. O novo ciclo se inicia no dia do pagamento com adicional do período inteiro do novo ciclo. Por esse motivo, aconselhamos o corte do serviço assim que uma assinatura entra no estado unpaid.

5. Status canceled

Após o cancelamento, nenhuma tentativa extra de cobrança é feita. Uma assinatura cancelada não pode ser cobrada novamente, então se o usuário quiser voltar a usar o seu serviço, ele precisa criar uma nova assinatura.

Cancelando a assinatura

Independentemente do momento ou do motivo, é possível cancelar uma assinatura através de:

curl -X POST 'https://api.pagar.me/1/subscriptions/{ID da Assinatura}/cancel' \
    -d 'api_key=SUA_API_KEY'

6. Upgrades e downgrades

6.1 Upgrades

No upgrade acontece uma cobrança, que é calculada da seguinte maneira:

**Se o status da assinatura não for paid, uma cobrança com o valor do novo plano é feita.

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

  1. É obtida a “proporção não usufruída” do plano com: (Dias não usados do plano antigo) / (Dias do plano antigo). Os dias não usados são o número de dias que faltam para chegar no current_period_end da assinatura.

  2. É obtido o “valor não usufruído” do plano antigo multiplicando essa “proporção não usufruída” pelo valor do plano antigo.

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

  4. 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 a soma de current_period_start + dias do plano.

Isso ocorre pois não existe motivo para cobrar o valor “não usado” do plano antigo no plano novo.

6.2 Downgrade

Não há nova cobrança, e a periodicidade é alterada:

1 - O current_period_start da assinatura passa a ser a data atual.

2 - O current_period_end do novo período é calculado da seguinte maneira:

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

Primeiro descobrimos o prorporcional do plano atual não utilizado pelo cliente.

dias restantes do plano atual = dias que faltam para o fim do período, correspondente ao current_period_end

valor restante do plano atual = (dias restantes do plano atual / dias do plano atual) * valor do plano atual

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

valor diário do novo plano = (valor do novo plano / dias do novo plano)

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

dias para a próxima cobrança = valor restante do plano atual / valor diário do novo plano

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

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

(dias não usados do plano antigo) / (dias do plano antigo).

Os dias não usados são o número de dias que faltam para chegar no current_period_end da assinatura.
É multiplicada essa "proporção não usufruída" pelo número de dias do novo plano, e o current_period_end da assinatura passa a ser esse número de dias, a partir da data atual.
Nesse calculo, 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.

Dúvidas frequentes

Quando uma assinatura vira unpaid, o serviço não é cortado. Quando o cliente volta a pagar, a periodicidade se altera; ou seja, o cliente consegue “ganhar” estes dias que ficaram como unpaid. Isto está certo?

Existem três status de uma assinatura: pending_payment, unpaid (com prazos de retentativa diferentes) e canceled. O comportamento esperado é que durante os dias de pending_payment o serviço não seja cancelado e que o cliente “ganhe” esses dias. Já, quando o status vira unpaid, um postback é enviado para a sua aplicação. Nessa situação, é esperado que o serviço seja suspenso na sua plataforma e que o seu assinante seja avisado de que o pagamento não foi realizado.

Ou seja, a sua aplicação deve controlar até qual momento o assinante pode acessar o serviço contratado. Essa é, inclusive, a razão de existir um status unpaid separado do status pending_payment.

O status canceled é irreversível. Isso quer dizer que uma nova assinatura precisa ser criada para que o acesso ao serviço/sistema seja continuado. Assim, ele só deveria ser atingido quando o cliente definitivamente não pagar ou quando ele quiser cancelar o serviço.

Após término do período de trial, qual a data efetiva de cobrança da assinatura?

Quando um plano é criado, são dados dois parâmetros: trial_days e days. Quando acaba o trial_days, a cobrança é efetuada imediatamente para o caso de cartão — para boleto, espera-se que o pagamento já tenha sido efetuado. Se a cobrança for realizada com sucesso, a próxima acontece ao final do periodo days que foi configurado no seu plano.

Se um usuário assinar um plano, usar o período trial, usar o plano e depois cancelar. Caso ele queira assinar novamente depois de algum tempo, o que acontece: gera um erro, a assinatura é feita sem trial, ou um novo período de trial é liberado?

Um novo período de trial é liberado. Entretanto, o controle desse comportamento pode ser gerenciado na sua aplicação. Para bloqueio do período de trial, você pode criar um plano sem período de trial, mas com os mesmos valores e periodicidade.

O que acontece na mudança de um plano padrão para um plano com trial?

O comportamento de upgrade/downgrade não se aplica. Isso quer dizer que, independentemente do acréscimo ou decréscimo no valor, é cobrado exatamente o valor da assinatura. O período ao final do trial não tem ajuste algum e é baseado integralmente no days do novo plano.

Updated 5 months ago


Próximo

No próximo passo você vai aprender a usar o gerenciamento de saldo do Pagar.me.

Overview

Fluxo de cobrança


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.