Planos

O plano é o primeiro objeto que precisa ser criado na nossa base de dados, antes de partir para criação de uma assinatura, já que ele é responsável por definir quando e quanto devemos cobrar do seu cliente.

Na prática, os planos são os produtos oferecidos aos seus clientes. A disponibilização dos planos possibilita que seus clientes criem as assinaturas.

Parâmetros de um plano

Cada parâmetro listado a seguir é responsável por definir alguma característica das assinaturas que serão criadas, sendo alguns deles indicados como obrigatórios para garantir o devido funcionamento de nosso sistema.

Veja a seguir a descrição dos parâmetros usados na criação de um plano:

Para aprender mais sobre planos, veja: Objeto Plano.

Mais informações sobre o parâmetro charges

Assim como foi explicado na tabela anterior, o parâmetro charges define quantas cobranças serão feitas ao assinante daquele plano. A seguir, colocamos dois cenários para ilustrar um pouco melhor este conceito:

Plano com days = 30, trial_days = 0, charges = 3

Para cartão de crédito: Nessas condições, serão feitas quatro cobranças no cartão do assinante, sendo:

• A primeira quando a assinatura é criada, neste momento o charges ainda não passou a ser contado.
• A segunda ( charges = 1), terceira ( charges = 2 ), quarta ( charges = 3 ), nas respectivas renovações mensais do plano.

Isso acontece porque o mecanismo de recorrência, que é responsável por controlar a contagem do charges, ainda não foi acionado. Dado esse princípio, você deve sempre ajustar o número de charges do plano de acordo com o modelo que deseja usar.

Para boleto bancário: Nessas condições serão feitas apenas três cobranças, pois apenas três boletos serão gerados. O parâmetro charges passa a ser contado no momento em que o mecanismo de recorrência identifica o primeiro pagamento junto ao banco emissor.

Plano com days = 30, trial_days = 30, charges = 3

Para cartão de crédito: Nessas condições, serão feitas 3 cobranças no cartão do assinante. A primeira ocorre através do mecanismo de recorrência, que identifica o término do período de trial e realiza uma tentativa de cobrança. Se essa tentativa for bem-sucedida, o mecanismo atualiza o parâmetro charges da assinatura. Ou seja:

• No momento de criação da assinatura não é feita nenhuma cobrança.
• No mês seguinte, dado que o período de trial foi finalizado, o primeiro (1/3) charge é feito.

Para boleto bancário: O comportamento é o mesmo que para cartão.

Outra função controlada pelo parâmetro charges é a possibilidade de cobrar um plano indefinidamente, ou até que alguém solicite seu cancelamento, para isso basta não enviar o parâmetro charges na requisição de criação do plano.

Quando isso é feito, a nossa API atribui o valor null para esse parâmetro e cobra o seu cliente da maneira que foi definida pelo plano. A diferença nesses casos é que não existe um número específico de parcelas que dita quando devemos encerrar as cobranças.

Criando um plano

Para criar um plano tudo que precisamos é que você envie uma requisição para a rota Criando Planos contendo pelo menos todos os parâmetros obrigatórios listados acima.

Exemplos de criação

Você pode usar os nossos SDKs para criar planos, ou fazer a chamada diretamente em nossa API. Veja alguns exemplos:

curl -X POST https://api.pagar.me/1/plans -H 'content-type: application/json' -d '{
    "amount": "31000", 
    "api_key": "SUA_API_KEY", 
    "days": "30", 
    "name": "Plano Ouro", 
    "payments_methods": ["credit_card"]
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.new({
    :name => "Plano ouro",
    :days => 30,
    :amount => 31000
}

plan.create

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

$plan = $pagarme->plans()->create([
  'amount' => '31000',
  'days' => '30',
  'name' => 'Plano ouro'
]);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Plan plan = new Plan
{
  	Name = "Plano ouro",
  	Amount = 31000,
  	Days = 3
};

plan.Save();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Plan;

PagarMe.init("SUA_API_KEY");

Plan plan = new Plan();
Integer amount = 31000;
Integer days = 30;
String name = "Plano ouro";
plan.setCreationParameters(amount, days, name);
plan.save();

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.create({
      amount: 31000,
      days: 30,
      name: 'Plano ouro'
  }))
  .then(plan => console.log(plan))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

plan_data = {
    "amount": "31000",
    "days": "30",
    "name": "Plano ouro"
}

plan = pagarme.plan.create(plan_data)

print (plan)

Alterando um plano

Somente é possível alterar os parâmetros name, trial_days e invoice_reminder de um plano. Para isso basta você criar uma requisição conforme indicado em Atualizando um plano.

Porém, vale ressaltar que, a alteração de um plano não altera as assinaturas já criadas com ele. Caso essa seja sua intenção, recomendamos a criação de um novo plano e a atualização de cada uma de suas assinaturas para conter o novo plano. Saiba mais sobre como atualizar uma assinatura em Atualizando o plano de uma assinatura.

Excluindo um plano

Não é possível excluir planos que foram criados com sucesso.