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

Criando um plano

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, você pode oferecer um ou mais planos para os seus clientes e então eles podem fazer a assinatura de uma dessas opções de recorrência.

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": ["boleto"]
}'
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_CHAVE_DE_API');

$plan = $pagarme->plans()->create([
  'amount' => '15000',
  'days' => '30',
  'name' => 'The Pro Plan - Platinum - Best ever'
]);
PagarMeService.DefaultApiKey = "SUA_API_KEY";

Plan plan = new Plan();
plan.Amount = 31000;
plan.Days = 30;
plan.Name = "Plano ouro";

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, trialDays, days, name);
plan.save();
import pagarme from 'pagarme'
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.create({
      amount: 31000,
      days: 30,
      name: 'Plano ouro',
      payments_methods: ['boleto'],
  }))
import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
    "amount": "10000",
    "days": "30",
    "trial_days": "0",
    "name": "Plan Test",
    "payment_methods": ["credit_card","boleto"]
}

plan = pagarme.plan.create(params)

print (plan)

É assim que você consegue criar um plano. Viu como é simples?

Configurações de um plano

Veja a seguir a descrição dos parâmetros usados nos exemplos anteriores:

parâmetros
default
descrição

name
Obrigatório

--

Nome do plano

amount
Obrigatório

--

Valor que será cobrado recorrentemente (em centavos). Ex: R$49,90 = 4990

days
Obrigatório

--

Prazo, em dias, para cobrança das parcelas. Ex: Para um plano mensal, days = 30.

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.
Ex: Plano cobrado 1x por ano, válido por no máximo 3 anos. Nesse caso, nossos parâmetros serão: days = 365, installments = 1, charges=2 (cartão de crédito) ou charges=3 (boleto).
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. Nesse caso, nossos parâmetros serão: days = 365, installments = 12, charges=2 (cartão de crédito) ou charges=3 (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

Observações e dúvidas frequentes

Consigo alterar um plano?

Sim, mas somente os atributos name, trial_days e invoice_reminder. Veja mais sobre como alterar um plano em: Atualizando Planos

Consigo excluir um plano?

Não, apenas alterar as propriedades comentadas na resposta anterior.

O parâmetro charges em mais detalhes

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

  1. 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 o 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 pagamento junto ao banco emissor.

  1. 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.

Como cobrar um plano indefinidamente?

Para cobrar um plano indefinidamente, ou até que o assinante solicite o seu cancelamento, basta não passar nenhum valor no parâmetro charges, assim como é mostrado nos exemplos da primeira seção.

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

Updated 7 months ago


Próximo

Agora que você já tem planos criados, pode começar a criar assinaturas.

Criando assinaturas

Criando um plano


Suggested Edits are limited on API Reference Pages

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