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

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:

Parâmetros

Padrão

Descrição

name
Obrigatório

--

Nome do plano.

amount
Obrigatório

--

Valor que será cobrado recorrentemente (em centavos). Deve ser no mínimo 1 real. Ex: R$49,90 = 4990.

days
Obrigatório

--

Prazo, em dias, para cobrança das parcelas. Ex: Para um plano mensal, days = 30.
OBS: O dia da cobrança não será constante.

trial_days

0

Dias para teste gratuito do plano. Valor começará a ser cobrado no dia trial_days + 1.

payment_methods

["boleto", "credit_card"]

Meios de pagamentos aceitos. Pode ser boleto, cartão de crédito ou ambos.

charges

null

Número de cobranças que poderão ser feitas nesse plano.
OBS: No caso de cartão de crédito, a cobrança feita na ativação da assinatura não é considerada.
OBS: null irá cobrar o usuário indefinidamente, ou até o plano ser cancelado.

installments

1

Número de parcelas entre cada cobrança (charges).
Ex: Plano anual, válido por 2 anos, sendo que cada transação será dividida em 12 vezes. Nossos parâmetros serão: days = 365, installments = 12, charges = 1 (cartão de crédito) ou charges = 2 (boleto).
OBS: Boleto sempre terá installments = 1.

invoice_reminder

--

Dias para que o cliente seja avisado sobre o vencimento do boleto.

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.

Updated 8 months ago


Próximo

Agora que você já criou seus planos, pode começar a aprender sobre as assinaturas.

Assinaturas

Planos


Suggested Edits are limited on API Reference Pages

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