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": "1000", 
    "api_key": "SUA_API_KEY", 
    "payment_method": "boleto", 
    "postback_url": "http://requestb.in/pkt7pgpk",
    "customer":{
      "name":"Aardvark da Silva",
      "document_number":"18152564000105"
    }
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY";

transaction  = PagarMe::Transaction.new({
    amount: 100,
  	payment_method: "boleto",
    postback_url: "http://requestb.in/pkt7pgpk",
    customer: {
        name: "Aardvark Silva",
        document_number: "18152564000105",
    }
})

transaction.charge

<?php
require("vendor/autoload.php");

$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$transaction = $pagarme->transactions()->create([
  "amount" => 1000,
  "payment_method" => "boleto",
  "async" => false,
  "postback_url" => "http://requestb.in/pkt7pgpk",
  "customer" => [
    "name" => "Aardvark Silva", 
    "document_number" => "18152564000105"
  ]
]);
?>

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Transaction transaction = new Transaction();

transaction.Amount = 1000;
transaction.PaymentMethod = PaymentMethod.Boleto;
transaction.PostbackUrl = "http://requestb.in/pkt7pgpk";
transaction.Customer = new Customer () {
    Name = "Aardvark Silva",
    DocumentNumber = "18152564000105",
};

transaction.Save();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Customer;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Customer customer = new Customer("Aardvark Silva");
customer.setDocumentNumber("18152564000105");

Transaction tx = new Transaction();
tx.setAmount(100);
tx.setPaymentMethod(PaymentMethod.BOLETO);
tx.setPostbackUrl("http://requestb.in/pkt7pgpk");
tx.setCustomer(customer);

tx.save();

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: {
        name: 'Aardvark Silva',
        document_number: '18152564000105',
  	},
  }))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
  'amount': '10000', 
  'payment_method': 'boleto',
  'customer': {
    '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'
    }
  }
}

trx = pagarme.transaction.create(params)

print (trx)

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-31T23:59:59.000Z
Tipo: string
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 '{
    "amount": "100", 
    "api_key": "SUA_API_KEY", 
    "customer": {
        "address": {
            "neighborhood": "Jardim Paulistano", 
            "street": "Avenida Brigadeiro Faria Lima", 
            "street_number": "1811", 
            "zipcode": "01451001"
        }, 
        "document_number": "18152564000105", 
        "email": "[email protected]", 
        "name": "Aardvark Silva", 
        "phone": {
            "ddd": "11", 
            "ddi": "55", 
            "number": "99999999"
        }
    }, 
    "metadata": {
        "idProduto": "13933139"
    }, 
    "payment_method": "boleto", 
    "postback_url": "http://requestb.in/pkt7pgpk"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY";

transaction  = PagarMe::Transaction.new({
    amount: 100,
  	payment_method: "boleto",
    postback_url: "http://requestb.in/pkt7pgpk",
    customer: {
        name: "Aardvark Silva",
        email: "[email protected]",
        document_number: "18152564000105",
        address: {
            street: "Avenida Brigadeiro Faria Lima",
            street_number: "1811",
            neighborhood: "Jardim Paulistano",
            zipcode: "01451001"
        },
        phone: {
            ddi: "55",
            ddd: "11",
            number: "99999999"
        }
    },
    metadata: {
        idProduto: "13933139"
    }
})

transaction.charge

<?php
require("vendor/autoload.php");

$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$transaction = $pagarme->transactions()->create([
  "amount" => 100,
  "payment_method" => "boleto",
  "postback_url" => "http://requestb.in/pkt7pgpk",
  "async" => false,
  "customer" => [
    "name" => "Aardvark Silva", 
    "document_number" => "18152564000105",
    "email" => "[email protected]",
    "address" => [
      "street" => "Avenida Brigadeiro Faria Lima", 
      "street_number" => "1811",
      "neighborhood" => "Jardim Paulistano",
      "zipcode" => "01451001"
    ],
    "phone" =>  [
      "ddi" => "55"
      "ddd" => "11",
      "number" => "99999999" 
    ]
  ],
  "metadata" => [
    "idProduto" => 13933139
  ]
]);
?>

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Transaction transaction = new Transaction();

transaction.Amount = 1000;
transaction.PaymentMethod = PaymentMethod.Boleto;

transaction.Customer = new Customer () {
    Name = "Aardvark Silva",
    Email = "[email protected]",
    DocumentNumber = "18152564000105",
  
    Address = new Address () {
        Street = "Avenida Brigadeiro Faria Lima",
        StreetNumber = "123",
        Neighborhood = "Jardim Paulistano",
        Zipcode = "01451001"
    },

    Phone = new Phone () {
        Ddi = "55",
        Ddd = "11",
        Number = "23456789"
    }
};

transaction.Save();

string boletoUrl = transaction.BoletoUrl;
string boletoBarcode = transaction.BoletoBarcode;

import java.util.HashMap;
import java.util.Map;

import me.pagar.model.Address;
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Phone;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

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);

Map<String, Object> metadata = new HashMap<String, Object>();
metadata.put("IdProduto", 13933139);

Transaction tx = new Transaction();
tx.setCustomer(customer);
tx.setAmount(100);
tx.setPaymentMethod(PaymentMethod.BOLETO);
tx.setMetadata(metadata);
tx.setPostbackUrl("http://requestb.in/pkt7pgpk");
tx.save();

import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
  'amount': '10000', 
  'payment_method': 'boleto',
  'customer': {
    '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'
    }
	}
}

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

📘

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á!