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 assinaturas

Para criar uma assinatura em nossa base de dados, é necessário ter no mínimo um plano já criado na sua conta. Caso você ainda não tenha, basta voltar à seção Criando um plano e aprender a fazer isso.

Com o plano criado, basta então realizar a criação da assinatura utilizando os parâmetros abaixo e seguindo os exemplos.

Criando uma assinatura

Exemplos de criação de assinaturas com payment method (método de pagamento) igual a credit_card:

curl -X POST https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "card_id": "card_ci234fx8rr649rt16rtb11132", 
    "customer": {
        "address": {
            "neighborhood": "Cidade Monções", 
            "street": "Rua Dr.Geraldo Campos Moreira", 
            "street_number": "240", 
            "zipcode": "04571020"
        }, 
        "document_number": "92545278157", 
        "email": "[email protected]", 
        "name": "John Appleseed", 
        "phone": {
            "ddd": "11", 
            "number": "15510101"
        }
    }, 
    "payment_method": "credit_card", 
    "plan_id": "12783", 
    "postback_url": "http://requestb.in/zyn5obzy"
}'
require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.find_by_id("12783")

subscription = PagarMe::Subscription.new({
    :payment_method => 'credit_card',
    :card_hash => "CARD_HASH_GERADO",
    :postback_url => "http://test.com/postback",
    :customer => {
        :name => "John Appleseed",
        :document_number => "92545278157",
        :email => "[email protected]",
        :address => {
            :street => "Rua Dr. Geraldo Campos Moreira",
            :neighborhood => "Cidade Monções",
            :zipcode => "04571020",
            :street_number => "240"
        },
        :phone => {
            :ddd => "11"
            :number => "15510101"
        }
    }
})
subscription.plan = plan

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

$subscription = $pagarme->subscriptions()->create([
  'plan_id' => 123456,
  'payment_method' => 'credit_card',
  'card_number' => '4111111111111111',
  'card_holder_name' => 'UNIX TIME',
  'card_expiration_date' => '0722',
  'card_cvv' => '123',
  'postback_url' => 'http://postbacj.url',
  'customer' => [
    'email' => '[email protected]',
    'name' => 'Unix Time',
    'document_number' => '75948706036',
    'address' => [
      'street' => 'Rua de Teste',
      'street_number' => '100',
      'complementary' => 'Apto 666',
      'neighborhood' => 'Bairro de Teste',
      'zipcode' => '11111111'
    ],
    'phone' => [
      'ddd' => '01',
      'number' => '923456780'
    ],
    'sex' => 'other',
    'born_at' => '1970-01-01',
  ],
  'metadata' => [
    'foo' => 'bar'
  ]
]);

?>
PagarMeService.DefaultApiKey = "SUA_API_KEY";
PagarMeService.DefaultEncryptionKey = "SUA ENCRYPTION KEY";

Subscription subscription = new Subscription();
subscription.PaymentMethod = PaymentMethod.CreditCard;
subscription.CardHash = "CARD_HASH_GERADO";

subscription.Customer = new Customer() {
    Name = "John Appleseed",
    DocumentNumber = "92545278157",
    Email = "[email protected]",
    Address = new Address() {
        Street = "Rua Dr. Geraldo Campos Moreira",
        Neighborhood = "Cidade Monções",
        Zipcode = "04571020",
        StreetNumber = "240"
    },
    Phone = new Phone() {
        Ddd = "11",
        Number = "15510101"
    }
};

subscription.Save();
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;

PagarMe.init("SUA_API_KEY");

Phone phone = new Phone();
phone.setDdd("11");
phone.setDdi("55");
phone.setNumber("99999999");

String street = "Avenida Brigadeiro Faria Lima";
String streetNumber = "1811";
String neighborhood = "Jardim Paulistano";
String zipcode = "01451001";
Address address = new Address(street, streetNumber, neighborhood, zipcode);

String name = "Aardvark Silva";
String email = "[email protected]";
String documentNumber = "18152564000105";
Customer customer = new Customer(name, email);
customer.setAddress(address);
customer.setPhone(phone);
customer.setDocumentNumber(documentNumber);

Card card = new Card();
card.setNumber("4901720080344448");
card.setHolderName("Jose da Silva");
card.setExpiresAt("1219");
card.setCvv(122);
card.save();

Subscription subscription = new Subscription();
subscription.setCreditCardSubscriptionWithCardId("122539", card.getId(), customer);
subscription.save();
import pagarme from 'pagarme'
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.create({
    plan_id: 1337,
    card_number: '4111111111111111',
    card_holder_name: 'abc',
    card_expiration_date: '1225',
    card_cvv: '123',
    customer: {
      email: '[email protected]'
    }
	}))
import pagarme

pagarme.authentication_key('SUA_API_KEY')

plan_params = {
    'amount': '10000',
    'days': '30',
    'trial_days': '0',
    'name': 'Credit card Plan',
    'payment_methods': ['credit_card']
}

plan = pagarme.plan.create(plan_params)

customer_params = {
    'email': '[email protected]',
    'name': 'Daenerys Targaryen',
    'document_number': '18152564000105',
    'address': {
        'zipcode': '04571020',
        'neighborhood': 'Dragon Village',
        'street': 'Rua Drogon',
        'street_number': '240'
    },
    'phone': {
        'number': '987654321',
        'ddd': '11'
    }
}

subscription_params = {
    'plan_id': plan['id'],
    'card_id': 'CARD_ID',
    'customer': customer_params,
    'payment_method':'credit_card',
    'postback_url': 'http://urlTeste.com'
}

subscription = pagarme.subscription.create(subscription_params)

print (subscription)

Exemplo de criação de assinatura com payment method (método de pagamento) igual a boleto:

curl -X POST https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "customer": {
        "email": "[email protected]"
    }, 
    "payment_method": "boleto", 
    "plan_id": "12783", 
    "postback_url": "http://requestb.in/zyn5obzy"
}'
require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.find_by_id("12783")

subscription = PagarMe::Subscription.new({
  :payment_method => 'boleto',
  :postback_url => "http://test.com/postback"
  :customer => {
    :email => '[email protected]'
  }
})
subscription.plan = plan

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

$subscription = $pagarme->subscriptions()->create([
  'plan_id' => 123456,
  'payment_method' => 'boleto',
  'postback_url' => 'http://postback.url',
  'customer' => [
    'email' => '[email protected]',
    'name' => 'Unix Time',
    'document_number' => '75948706036',
    'address' => [
      'street' => 'Rua de Teste',
      'street_number' => '100',
      'complementary' => 'Apto 666',
      'neighborhood' => 'Bairro de Teste',
      'zipcode' => '11111111'
    ],
    'phone' => [
      'ddd' => '01',
      'number' => '923456780'
    ],
    'sex' => 'other',
    'born_at' => '1970-01-01',
  ],
  'metadata' => [
    'foo' => 'bar'
  ]
]);

?>
PagarMeService.DefaultApiKey = "SUA_API_KEY";

Subscription subscription = new Subscription();
subscription.PaymentMethod = PaymentMethod.Boleto;

subscription.Customer = new Customer() {
    Email = "[email protected]"
};

subscription.Save();
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;

PagarMe.init("SUA_API_KEY");

Phone phone = new Phone();
phone.setDdd("11");
phone.setDdi("55");
phone.setNumber("99999999");

String street = "Avenida Brigadeiro Faria Lima";
String streetNumber = "1811";
String neighborhood = "Jardim Paulistano";
String zipcode = "01451001";
Address address = new Address(street, streetNumber, neighborhood, zipcode);

String name = "Aardvark Silva";
String email = "[email protected]";
String documentNumber = "18152564000105";
Customer customer = new Customer(name, email);
customer.setAddress(address);
customer.setPhone(phone);
customer.setDocumentNumber(documentNumber);

Subscription subscription = new Subscription();
subscription.setBoletoSubscription("122539", customer);
subscription.save();
import pagarme from 'pagarme'
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.create({
    plan_id: 1337,
    postback_url: 'http://requestb.in/zyn5obzy',
    payment_method: 'boleto',
    customer: {
      email: '[email protected]'
    }
	}))
import pagarme

pagarme.authentication_key('SUA_API_KEY')

plan_params = {
    'amount': '10000',
    'days': '30',
    'trial_days': '0',
    'name": 'Boleto Plan',
    'payment_methods': ['boleto']
}

plan = pagarme.plan.create(plan_params)

customer_params = {
    'email': '[email protected]',
    'name': 'Daenerys Targaryen',
    'document_number': '18152564000105',
    'address': {
        'zipcode': '04571020',
        'neighborhood': 'Dragon Village',
        'street': 'Rua Drogon',
        'street_number': '240'
    },
    'phone': {
        'number': '987654321',
        'ddd': '11'
    }
}

subscription_params = {
    'plan_id': plan['id'],
    'customer': customer_params,
    'payment_method': 'boleto',
    'postback_url': 'http://urlTeste.com'
}

subscription = pagarme.subscription.create(subscription_params)

print (subscription)

Parâmetros de uma assinatura

Aprenda um pouco mais sobre o que cada parâmetro usado nos exemplos anteriores significa, e como ajustá-los para a sua aplicação:

parâmetros
default
descrição

plan_id
obrigatório

--

ID do plano a ser associado a uma assinatura

card_hash ou card_id
obrigatório (caso payment_method igual credit_card)

--

Dados encriptados do cartão do cliente. Você também pode usar o card_id ao invés do card_hash

postback_url

--

URL de sua aplicação, para a qual a nossa API envia requisições informando cada alteração de status da assinatura em questão

metadata

--

Você pode passar dados adicionais na criação da transação para posteriormente filtrar essas informações na nossa Dashboard. Ex: metadata [idProduto]=13933139

customer[email]
obrigatório

--

E-mail do cliente

customer[name]
obrigatório (com antifraude)

--

Nome completo ou razão social do cliente

customer[gender]

--

Gênero do cliente

custome[born_at]

--

Data de nascimento do cliente. Formato (exemplo): 2017-05-19T21:59:54.832Z

customer[document_number]
obrigatório (com antifraude)

--

CPF ou CNPJ do cliente, sem separadores

customer[address][street]
obrigatório (com antifraude)

--

logradouro (rua, avenida, etc) do cliente

customer[address][street_number]
obrigatório (com antifraude)

--

Número da residência/estabelecimento do cliente

customer[address][complementary]

--

complemento do endereço do cliente

customer[address][neighborhood]
obrigatório (com antifraude)

--

bairro de localização do cliente

customer[address][zipcode]
obrigatório (com antifraude)

--

CEP do imóvel do cliente, sem separadores

customer[phone][ddd]
obrigatório (com antifraude)

--

DDD do telefone do cliente

customer[phone][number]
obrigatório (com antifraude)

--

número do telefone do cliente

Para aprender sobre todos os parâmetros possíveis na criação de uma assinatura, veja: Objeto Assinatura

Por que é obrigatório passar dados de customer na assinatura com Cartão de crédito?

Para recorrência com cartão de crédito, a primeira transação é analisada pelo antifraude. Por esse motivo todos os dados de customer são necessários.

Criando assinaturas com Split de transação

Além de cobrar o seu cliente de forma recorrente, você pode também fazer um split (divisão) dos valores gerados a cada transação criada. Para isso, além de passar os campos do exemplo anterior você deve passar também as regras de split. Veja o exemplo:

curl -X POST -H "Content-Type: application/json"  -d '{
  "api_key":"SUA API KEY",
  "card_number": "4242424242424242",
  "card_cvv": "122",
  "card_holder_name": "Aardvark Silva",
  "card_expiration_date": "1220",
  "customer":{
    "email":"[email protected]",
    "name":"nome",
    "document_number":"35965816804",
    "address":{
      "zipcode":"06350270",
      "neighborhood":"bairro",
      "street":"rua",
      "street_number":"122"
    },
    "phone": {
      "number":"87654321",
      "ddd":"11"
    }
  } ,
  "plan_id":"89226",
  "amount": 10000,
  "split_rules": [
    {
      "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk",
      "percentage": 20,
      "liable": true,
      "charge_processing_fee": true
    },{
      "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
      "percentage": 80,
      "liable": true,
      "charge_processing_fee": true
    }
  ]
}' "https://api.pagar.me/1/subscriptions"
require 'pagarme'

PagarMe.api_key = "SUA API KEY"

plan = PagarMe::Plan.find_by_id("12783")

subscription = PagarMe::Subscription.new({
    :payment_method => 'credit_card',
    :card_number => "4901720080344448",
    :card_holder_name => "Jose da Silva",
    :card_expiration_month => "10",
    :card_expiration_year => "15",
    :card_cvv => "314",
    :postback_url => "http://test.com/postback",
    :customer => {
        email: '[email protected]'
    },
    :split_rules: [
        {
          recipient_id: "re_cj2wd5ul500d4946do7qtjrvk",
          percentage: 10,
          liable: true,
          charge_processing_fee: true
        } ,
        {
          recipient_id: "re_cj2wd5u2600fecw6eytgcbkd0",
          percentage: 90,
          liable: true,
          charge_processing_fee: true
        } 
    ])
subscription.plan = plan

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

$subscription = $pagarme->subscriptions()->create([
  'plan_id' => 123456,
  'card_id' => 'card_abc123456',
  'payment_method' => 'credit_card',
  'postback_url' => 'http://www.pudim.com.br',
  'customer' => [
    'email' => '[email protected]',
    'name' => 'Unix Time',
    'document_number' => '75948706036',
    'address' => [
      'street' => 'Rua de Teste',
      'street_number' => '100',
      'complementary' => 'Apto 666',
      'neighborhood' => 'Bairro de Teste',
      'zipcode' => '88370801'
    ],
    'phone' => [
      'ddd' => '01',
      'number' => '923456780'
    ],
    'sex' => 'other',
    'born_at' => '1970-01-01',
  ],
  'split_rules' => [
    [
      'recipient_id' => 're_abc1234abc1234abc1234abc1',
      'percentage' => 20,
      'liable' => true,
      'charge_processing_fee' => true,
    ],
    [
      'recipient_id' => 're_abc1234abc1234abc1234abc1',
      'percentage' => 80,
      'liable' => true,
      'charge_processing_fee' => true,
    ]
  ],
  'metadata' => [
    'foo' => 'bar'
  ]
]);
const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA API KEY' })
    .then(client => client.subscriptions.create({
        plan_id: 133163,
        payment_method: 'boleto',
        customer: {
            email: '[email protected]'
        },
        split_rules: [
            {
                'recipient_id': 're_ciyoloogb0100l46dy6f1iuww',
                'liable': 'true',
                'charge_processing_fee': 'true',
                'percentage': '55',
            },
            {
                'recipient_id': 're_ciyol0qac00xnlg6dkaftvn9j',
                'liable': 'false',
                'charge_processing_fee': 'false',
                'percentage': '45',
            }
        ]
    }))
    .then(subscription => console.log(subscription))
    .catch(error => console.log(error))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription_params = {
  "card_number": "4242424242424242",
  "card_cvv": "122",
  "card_holder_name": "Aardvark Silva",
  "card_expiration_date": "1220",
  "customer":{
    "email":"[email protected]",
    "name":"nome",
    "document_number":"35965816804",
    "address":{
      "zipcode":"06350270",
      "neighborhood":"bairro",
      "street":"rua",
      "street_number":"122"
    },
    "phone": {
      "number":"87654321",
      "ddd":"11"
    }
  } ,
  "plan_id":"89226",
  "amount": 10000,
  "split_rules": [
    {
      "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk",
      "percentage": 20,
      "liable": true,
      "charge_processing_fee": true
    },{
      "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
      "percentage": 80,
      "liable": true,
      "charge_processing_fee": true
    }
  ]
}

subscription = pagarme.subscription.create(subscription_params)

print (subscription)

Criando assinatura com o Checkout Pagar.me

Para usar o Checkout Pagar.me com o nosso sistema de assinaturas, você precisa utilizar a propriedade create-token como false. Isso possibilita a captura dos dados inseridos no formulário e o retorno deles para a sua plataforma. Dessa forma, já na sua plataforma você consegue fazer a chamada para criação das assinaturas, assim como nos exemplos anteriores.

Para entender mais sobre a diferença entre create-token true e false, acesse Inserindo o Checkout .

Veja o exemplo abaixo com create-token = false:

<form method="POST" action="/comprar">
    <script type="text/javascript"
        src="https://assets.pagar.me/checkout/checkout.js"
        data-button-text="Pagar"
        data-encryption-key="ek_test_Ec8KhxISQ1tug1b8bCGxC2nXfxqRmk"
        data-amount="1000"
        data-create-token="false">
    </script>
</form>
<html>
    <head>
        <!-- SCRIPT PAGAR.ME -->
        <script src="https://assets.pagar.me/checkout/checkout.js"></script>
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
    </head>
    <body>
        <button id="pay-button">Abrir modal de pagamento</button>

        <script>
            $(document).ready(function() {
                var button = $('#pay-button');

                button.click(function() {

                    // INICIAR A INSTÂNCIA DO CHECKOUT
                    // declarando um callback de sucesso
                    var checkout = new PagarMeCheckout.Checkout({"encryption_key":"ENCRYPTION KEY", success: function(data) {
                        console.log(data);
                        //Tratar aqui as ações de callback do checkout, como exibição de mensagem ou envio de token para captura da transação
                    }});

                    // DEFINIR AS OPÇÕES
                    // e abrir o modal
                    // É necessário passar os valores boolean em "var params" como string
                    var params = {"customerData":"false", "amount":"100000", "createToken": "false", "interestRate": 10 };
                    checkout.open(params);
                });
            });
        </script>
    </body>
</html>

Usando essa configuração o Checkout captura as informações inseridas no formulário e envia para o action que você especificou, ou retorna no callback de sucesso, caso você esteja usando a versão JS.

Os dados retornados são: customer (incluindo nome, email, endereço), payment_method escolhido (boleto ou credit_card) e, caso Cartão de crédito tenha sido escolhido como método de pagamento, o Checkout também gera e envia um card_hash.

O próximo passo é tratar essas informações, e usar um dos exemplos acima para criar a assinatura.

Dando baixa em uma cobrança de assinatura

Assim como foi mencionado no Overview, se uma assinatura estiver com o status unpaid ou pending_payment, é possível dar baixa na respectiva parcela que não foi paga. Quando você faz isso, a assinatura volta a ter status paid e novas cobranças podem ser feitas normalmente.

É possível negociar e cobrar diretamente com o cliente essas parcelas que você deu baixa, sem interferir no fluxo da assinatura. Veja o exemplo:

curl -X POST https://api.pagar.me/1/subscriptions/208686/settle_charge -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$settledCharges = $pagarme->subscriptions()->settleCharges([
    'id' => 12345,
    'charges' => 5
]);

Exemplo de resposta após requisição na rota /settle_charge :

{
  "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": 208686,
  "current_transaction": null,
  "postback_url": "https://requestb.in/10m5xva1",
  "payment_method": "boleto",
  "card_brand": null,
  "card_last_digits": null,
  "current_period_start": "2017-06-29T20:18:15.056Z",
  "current_period_end": "2017-07-29T20:18:15.056Z",
  "charges": 1,
  "status": "paid",
  "date_created": "2017-06-29T20:16:22.490Z",
  "phone": {
    "object": "phone",
    "ddi": "55",
    "ddd": "614",
    "number": "33404556",
    "id": 23325
  },
  "address": {
    "object": "address",
    "street": "Rua da Consolação",
    "complementary": null,
    "street_number": "34",
    "neighborhood": "Higienópolis",
    "city": "São Paulo",
    "state": "SP",
    "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": {
    "morphin": "mighty"
  },
  "settled_charges": [
    1
  ]
}

Perceba as seguintes mudanças na resposta:

  • status da assinatura: volta para paid.
  • current_transaction: vai ficar como null e será preenchido somente quando o período da assinatura chegar ao fim, e a cobrança de renovação acontecer.
  • settled_charges: representa uma lista com as cobranças que tiveram baixa, durante todo o ciclo de vida da assinatura, para que você tenha esse controle.

Mais operações com assinaturas

Você pode aprender mais sobre as rotas de nossa API que envolvem assinaturas em: Referência API

Updated about a month ago


Próximo

Agora que você já sabe como criar planos e assinaturas, é hora de aprender sobre todo o fluxo de cobrança de Recorrência.

Fluxo de cobrança

Criando assinaturas


Suggested Edits are limited on API Reference Pages

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