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

Boleto bancário

Uma transação com boleto bancário é a forma mais simples de emitir uma cobrança para o seu cliente usando o Pagar.me. Veja o exemplo:

curl -X POST 'https://api.pagar.me/1/transactions' -H 'content-type: application/json' -d '{
    "amount": 2100, 
    "api_key": "SUA_API_KEY",
    "payment_method": "boleto",
    "customer":{
        "type": "individual",
        "country": "br",
        "name": "Daenerys Targaryen",
        "documents": [{
            "type": "cpf",
            "number": "00000000000"
        }]
    }
}'
<?php
$transaction = $pagarme->transactions()->create([
  'amount' => 1000,
  'payment_method' => 'boleto',
  'async' => false,
  'customer' => [
    'external_id' => '1',
    'name' => 'Nome do cliente',
    'type' => 'individual',
    'country' => 'br',
    'documents' => [
      [
        'type' => 'cpf',
        'number' => '00000000000'
      ]
    ],
    'phone_numbers' => [ '+551199999999' ],
    'email' => '[email protected]'
  ]
]);
import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.create({
    amount: 1000,
    payment_method: 'boleto',
    postback_url: 'http://requestb.in/pkt7pgpk',
    customer: {
      type: 'individual',
      country: 'br',
      name: 'Aardvark Silva',
      documents: [
        {
          type: 'cpf',
          number: '00000000000',
        },
      ],
    },
  }))
import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
  'amount': '10000', 
  'payment_method': 'boleto',
  'customer': {
    'type': 'individual',
    'country': 'br',
    'email': '[email protected]',
    'name': 'Daenerys Targaryen',
    'documents': [
      {
        'type': 'cpf',
        'number': '00000000000'
      }
    ]
  }
}

trx = pagarme.transaction.create(params)

print (trx)
using System;
using System.Collections.Generic;
using System.Linq;
using PagarMe;
using Newtonsoft.Json;
using PagarMe.Model;

PagarMeService.DefaultApiKey = "SUA_CHAVE_DE_API";
PagarMeService.DefaultEncryptionKey = "SUA_CHAVE_DE_CRIPTOGRAFIA";

Transaction transaction = new Transaction();

transaction.Amount = 2100;
transaction.Card = new Card
{
  Id = "card_cj95mc28g0038cy6ewbwtwwx2"
};

transaction.Customer = new Customer
{
  ExternalId = "#3311",
  Name = "Rick",
  Type = CustomerType.Individual,
  Country = "br",
  Email = "[email protected]",
  Documents = new[]
  {
    new Document{
      Type = DocumentType.Cpf,
      Number = "11111111111"
    },
    new Document{
      Type = DocumentType.Cnpj,
      Number = "83134932000154"
    }
  },
  PhoneNumbers = new string[]
  {
    "+5511982738291",
    "+5511829378291"
  },
  Birthday = new DateTime(1991, 12, 12).ToString("yyyy-MM-dd")
};

transaction.Save();

Não se esqueça de incluir a sua chave de API, que está disponível em sua Dashboard.

Status da transação

Para boletos registrados, o fluxo da transação é o seguinte:

Depois que o cliente finaliza a compra no site e gera o boleto, a transação tem o status processing até que o boleto seja de fato gerado ou registrado — até 24/03/2018, apenas documentos com valor igual ou maior do que 2.000 reais passam por registro.

Após esse passo, o boleto é gerado e a transação fica então com o status waiting_payment até que o pagamento seja efetuado.

A URL do boleto bancário para pagamento estará disponível na variável boleto_url. Lembrando que esse valor não é retornado no ambiente de testes, sendo que o parâmetro "boleto_url" é preenchido com o seguinte link "https://pagar.me".

Quando o boleto bancário é detectado como pago, a transação passa a ter o
status paid.

Mais parâmetros

Além dos parâmetros passados no exemplo, você ainda pode usar:

Parâmetro

Padrão

Descrição

amount


Valor total a ser cobrado (em centavos). Ex: R$14,99 = 1499
Tipo: integer

boleto_instructions

Instruções da dashboard

Campo instruções do boleto. Máximo de 255 caracteres. Obs. Utilizar \n para quebra de linha
Tipo: string

boleto_expiration_date

data atual + 7 dias

Data de vencimento do boleto bancário em ISODate. Exemplo: 2017-12-31
Tipo: string

capture

true

Após a autorização de uma transação, você pode escolher se irá capturar ou adiar a captura do valor. Caso opte por postergar a captura, atribua o valor false.
Tipo: boolean

postback_url


URL para receber notificações sobre alterações do status da transação
Tipo: string

boleto_fine.days


Dias após a expiração do boleto quando a multa deve ser cobrada.
Tipo: integer

boleto_fine.amount


Valor em centavos da multa.
Tipo: integer

boleto_fine.percentage


Valor em porcentagem da multa.
Tipo: number

boleto_interest.days


Dias após a expiração do boleto quando o juros deve ser cobrado.
Tipo: integer

boleto_interest.amount


Valor em centavos da taxa de juros que será cobrado por dia.
Tipo: integer

boleto_interest.percentage


Valor em porcentagem da taxa de juros que será cobrado por dia.
Tipo: number

boleto_rules


Permite aplicar regras ao boleto emitido. Valores possíveis: 'strict_expiration_date' (restringe o pagamento para até a data de vencimento e apenas o valor exato do documento), 'no_strict' (permite pagamento após o vencimento e valores diferentes do impresso)
Tipo: array

❗️

Limites para juros e multas

Há um limite dado pelo prestador de serviços para essas transações. Caso o valor das taxas ultrapassem o limite, as transações serão recusadas. Esses limites são:

Multa: Valor máximo de 2% do valor do documento.
Juros: Valor máximo de 1% ao mês.

📘

Boleto em PDF

Além da versão HTML dos boletos retornada pela API, é possível gerar uma versão em PDF. Para tal basta adicionar o sufixo ?format=pdf na url retornada. Segue um exemplo:
URL ORIGINAL: https://api.pagar.me/1/boletos/test_ckj9yiyvy1obb0gm5g9yfpgbw
URL PDF: https://api.pagar.me/1/boletos/test_ckj9yiyvy1obb0gm5g9yfpgbw?format=pdf

📘

Captura de transação no Boleto Bancário

Para transações realizadas com encryption_key o valor padrão do capture é false, porém você pode realizar a captura alterando o valor para true. Somente para Boleto Bancário.

📘

Código de Barras e Link para Download do Boleto Bancário

Para obter o Código de Barras e o Link para Download do Boleto você deve passar o parâmetro capture como true. Ou você pode realizar a captura posteriormente através da rota /capture, para mais informações clique aqui.

Aprenda mais sobre a lista completa de parâmetros em: Criar transação

O Boleto bancário resultante tem os parâmetros mostrados como este:

Boleto resultante

Dados do cliente no boleto

Sempre que possível, passe mais informações do seu cliente no momento da criação da transação de Boleto bancário. Faça isso para facilitar a identificação da transação tanto na sua Dashboard quanto no seu próprio sistema.

curl -X POST https://api.pagar.me/1/transactions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY",
    "amount": 21000,
    "payment_method": "boleto",
    "customer": {
        "external_id": "#3311",
        "name": "Morpheus Fishburne",
        "type": "individual",
        "country": "br",
        "email": "[email protected]",
        "documents": [
            {
                "type": "cpf",
                "number": "00000000000"
            }
        ],
        "phone_numbers": ["+5511999998888", "+5511888889999"],
        "birthday": "1965-01-01"
    },
    "billing": {
        "name": "Trinity Moss",
        "address": {
            "country": "br",
            "state": "sp",
            "city": "Cotia",
            "neighborhood": "Rio Cotia",
            "street": "Rua Matrix",
            "street_number": "9999",
            "zipcode": "06714360"
        }
    },
    "shipping": {
        "name": "Neo Reeves",
        "fee": 1000,
        "delivery_date": "2000-12-21",
        "expedited": true,
        "address": {
            "country": "br",
            "state": "sp",
            "city": "Cotia",
            "neighborhood": "Rio Cotia",
            "street": "Rua Matrix",
            "street_number": "9999",
            "zipcode": "06714360"
        }
    },
    "items": [
        {
            "id": "r123",
            "title": "Red pill",
            "unit_price": 10000,
            "quantity": 1,
            "tangible": true
        },
        {
            "id": "b123",
            "title": "Blue pill",
            "unit_price": 10000,
            "quantity": 1,
            "tangible": true
        }
    ]
}'
require 'pagarme'

PagarMe.api_key = "SUA_API_KEY";

transaction  = PagarMe::Transaction.new({
  amount: 100,
  payment_method: "credit_card",
  card_number: "4111111111111111",
  card_holder_name: "Morpheus Fishburne",
  card_expiration_date: "1123",
  card_cvv: "123",
  postback_url: "http://requestb.in/pkt7pgpk",
  customer: {
    external_id: "#3311",
    name: "Morpheus Fishburne",
    type: "individual",
    country: "br",
    email: "[email protected]",
    documents: [
      {
        type: "cpf",
        number: "30621143049"

      }

    ],
    phone_numbers: ["+5511999998888", "+5511888889999"],
    birthday: "1965-01-01"
  },
  billing: {
    name: "Trinity Moss",
    address: {
      country: "br",
      state: "sp",
      city: "Cotia",
      neighborhood: "Rio Cotia",
      street: "Rua Matrix",
      street_number: "9999",
      zipcode: "06714360"
    }
  },
  shipping: {
    name: "Neo Reeves",
    fee: 1000,
    delivery_date: "2000-12-21",
    expedited: true,
    address: {
      country: "br",
      state: "sp",
      city: "Cotia",
      neighborhood: "Rio Cotia",
      street: "Rua Matrix",
      street_number: "9999",
      zipcode: "06714360"
    }
  },
  items: [
    {
      id: "r123",
      title: "Red pill",
      unit_price: 10000,
      quantity: 1,
      tangible: true
    },
    {
      id: "b123",
      title: "Blue pill",
      unit_price: 10000,
      quantity: 1,
      tangible: true
    }

  ]
})

transaction.charge
<?php
$transaction = $pagarme->transactions()->create([
  'amount' => 1000,
  'payment_method' => 'boleto',
  'async' => false,
  'customer' => [
    'external_id' => '1',
    'name' => 'Nome do cliente',
    'type' => 'individual',
    'country' => 'br',
    'documents' => [
      [
        'type' => 'cpf',
        'number' => '00000000000'
      ]
    ],
    'phone_numbers' => [ '+551199999999' ],
    'email' => '[email protected]'
  ]
]);
using System;
using PagarMe;

PagarMeService.DefaultApiKey = "API_KEY";
PagarMeService.DefaultEncryptionKey = "ENCRYPTION_KEY";

Transaction transaction = new Transaction();

transaction.Amount = 2100;
transaction.Card = new Card
{
  Id = "card_cj95mc28g0038cy6ewbwtwwx2"
};

transaction.Customer = new Customer
{
  ExternalId = "#3311",
  Name = "Rick",
  Type = CustomerType.Individual,
  Country = "br",
  Email = "[email protected]",
  Documents = new[]
  {
    new Document{
      Type = DocumentType.Cpf,
      Number = "30621143049"
    },
    new Document{
      Type = DocumentType.Cnpj,
      Number = "83134932000154"
    }
  },
  PhoneNumbers = new string[]
  {
    "+5511982738291",
    "+5511829378291"
  },
  Birthday = new DateTime(1991, 12, 12).ToString("yyyy-MM-dd")
};

transaction.Billing = new Billing 
{
  Name = "Morty",
  Address = new Address()
  {
    Country = "br",
    State = "sp",
    City = "Cotia",
    Neighborhood = "Rio Cotia",
    Street = "Rua Matrix",
    StreetNumber = "213",
    Zipcode = "04250000"
  }
};

var Today = DateTime.Now;

transaction.Shipping = new Shipping 
{ 
  Name = "Rick",
  Fee = 100,
  DeliveryDate = Today.AddDays(4).ToString("yyyy-MM-dd"),
  Expedited = false,
  Address = new Address()
  {
    Country = "br",
    State = "sp",
    City = "Cotia",
    Neighborhood = "Rio Cotia",
    Street = "Rua Matrix",
    StreetNumber = "213",
    Zipcode = "04250000"
  }
};

transaction.Item = new[]
{
  new Item()
  {
    Id = "1",
    Title = "Little Car",
    Quantity = 1,
    Tangible = true,
    UnitPrice = 1000
  },
  new Item()
  {
    Id = "2",
    Title = "Baby Crib",
    Quantity = 1,
    Tangible = true,
    UnitPrice = 1000
  }
};

transaction.Save();
import java.util.ArrayList;
import java.util.Collection;
import me.pagar.model.Address;
import me.pagar.model.Billing;
import me.pagar.model.Customer;
import me.pagar.model.Document;
import me.pagar.model.Item;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Shipping;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Transaction transaction = new Transaction();
Customer customer = new Customer();
customer.setType(Customer.Type.INDIVIDUAL);
customer.setExternalId("1001");
customer.setName("Phineas Flynn");
customer.setBirthday("1999-07-09");
customer.setEmail("[email protected]");
customer.setCountry("br");

Collection<Document> documents = new ArrayList();
Document document = new Document();
document.setType(Document.Type.CPF);
document.setNumber("77551442758");
documents.add(document);
customer.setDocuments(documents);

Collection<String> phones = new ArrayList();
phones.add("+5511982657575");
customer.setPhoneNumbers(phones);

Billing billing = new Billing(); 
billing.setName("Phineas Flynn");
Address address  = new Address(); 
address.setCity("Santo Andre");
address.setCountry("br");
address.setState("sp");
address.setNeighborhood("Parque Miami");
address.setStreet("Rua Rio Jari");
address.setZipcode("09133180");
address.setStreetNumber("7");
billing.setAddress(address);

Shipping shipping = new Shipping();
shipping.setAddress(address);
shipping.setName("Phineas Flynn");
shipping.setFee(3200);

Collection<Item> items = new ArrayList();
Item item = new Item(); 
item.setId("OX890");
item.setQuantity(12);
item.setTangible(Boolean.TRUE);
item.setTitle("Rockets");
item.setUnitPrice(120);

transaction.setShipping(shipping);
transaction.setBilling(billing);
transaction.setItems(items);
transaction.setPaymentMethod(Transaction.PaymentMethod.CREDIT_CARD);
transaction.setAmount(4640);
transaction.setCardHolderName("Phineas Flynn");
transaction.setCardNumber("4242424242424242");
transaction.setCardCvv("909");
transaction.setCardExpirationDate("1119"); 
transaction.setCustomer(customer);
transaction.save();
const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.create({
    "amount": 21000,
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "card_expiration_date": "0922",
    "card_holder_name": "Morpheus Fishburne",
    "customer": {
      "external_id": "#3311",
      "name": "Morpheus Fishburne",
      "type": "individual",
      "country": "br",
      "email": "[email protected]",
      "documents": [
        {
          "type": "cpf",
          "number": "30621143049"
        }
      ],
      "phone_numbers": ["+5511999998888", "+5511888889999"],
      "birthday": "1965-01-01"
    },
    "billing": {
      "name": "Trinity Moss",
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "shipping": {
      "name": "Neo Reeves",
      "fee": 1000,
      "delivery_date": "2000-12-21",
      "expedited": true,
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "items": [
      {
        "id": "r123",
        "title": "Red pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      },
      {
        "id": "b123",
        "title": "Blue pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      }
    ]
  }))
  .then(transaction => console.log(transaction))
import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
        "amount": "21000",
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "card_expiration_date": "0922",
    "card_holder_name": "Morpheus Fishburne",
    "customer": {
      "external_id": "#3311",
      "name": "Morpheus Fishburne",
      "type": "individual",
      "country": "br",
      "email": "[email protected]",
      "documents": [
        {
          "type": "cpf",
          "number": "30621143049"
        }
      ],
      "phone_numbers": ["+5511999998888", "+5511888889999"],
      "birthday": "1965-01-01"
    },
    "billing": {
      "name": "Trinity Moss",
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "shipping": {
      "name": "Neo Reeves",
      "fee": "1000",
      "delivery_date": "2000-12-21",
      "expedited": True,
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "items": [
      {
        "id": "r123",
        "title": "Red pill",
        "unit_price": "10000",
        "quantity": "1",
        "tangible": True
      },
      {
        "id": "b123",
        "title": "Blue pill",
        "unit_price": "10000",
        "quantity": "1",
        "tangible": True
      }
    ]
}

trx = pagarme.transaction.create(params)

print(trx)

🚧

Dados obrigatórios

Além do valor a ser pago (amount) e do método de pagamento (payment_method), para a criação de transações de boleto é obrigatório informar também os parâmetros customer.name e customer.documents.

📘

Simulando o pagamento de um boleto em teste

Você pode simular o pagamento do boleto usando a seguinte chamada:

curl -X PUT https://api.pagar.me/1/transactions/:TRANSACTION_ID \
-d 'api_key=SUA_API_KEY' \
-d 'status=paid'

Updated 2 months ago


Próximo

Nessa altura sua integração conosco já deve ter cartão de crédito e boleto. Legal, que tal aprender agora o que é metadata? Esta feature pode ajudar bastante o seu negócio. Vamos lá!

Usando Metadata

Boleto bancário


Suggested Edits are limited on API Reference Pages

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