GuidesSuporteAPI Reference

Boleto bancário

Suggest Edits

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",
    "boleto_fine": {
        "days": "1",
        "amount": "1"
    },
    "boleto_interest": {
        "days": "1",
        "amount": "1"
    }
    "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âmetroPadrãoDescrição
amount---Valor total a ser cobrado (em centavos). Ex: R$14,99 = 1499
Tipo: integer
boleto_instructionsInstruções da dashboardCampo instruções do boleto. Máximo de 255 caracteres. Obs. Utilizar \n para quebra de linha
Tipo: string
boleto_expiration_datedata atual + 7 diasData de vencimento do boleto bancário em ISODate. Exemplo: 2017-12-31
Tipo: string
capturetrueApó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 ao dia.
Tipo: integer
boleto_interest.percentage---Valor em porcentagem da taxa de juros que será cobrado ao mês.
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

Não recomendamos o uso de taxas de juros superiores a 1% a.m e valores de multa superiores a 2% a.m devido as regulações determinadas pelos artigos 52, parágrafo primeiro do código de defesa do consumidor e art. 406, do Código Civil e 161 parágrafo primeiro do Código Tributário Nacional.

📘

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:

878

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'

Emisores de boleto

O Pagar.Me possui múltiplos emissores de boleto e pode utilizar um ou outro dependendo de alguns fatores internos, como performance e funcionalidades integradas.

Sendo assim, após a finalização de uma compra com boleto iremos disponibilizar uma URL com um boleto registrado, esse boleto pode ser tanto do Bradesco quanto da Caixa Economica Federal.

Independente do emissor do boleto, a criação da transação e as informações retornadas na resposta desta operação são as mesmas. Já o layout apresentado para o consumidor pode variar de acordo com o banco onde o boleto foi emitido.

Abaixo é possivel verificar o layout de cada emissor.

1696

Updated almost 3 years 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á!