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.

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

boleto_instructions

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

boleto_expiration_date

data atual + 7 dias

Data de vencimento do boleto bancário em ISODate.

Exemplo: 2017-12-31

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.

postback_url

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

boleto_fine

data de cobrança da multa e o valor desta

boleto_fine[days]

dias após a expiração do boleto a multa deve ser cobrada.

boleto_fine[amount]

valor em centavos da multa.

boleto_interest

mecanismo de cobrança de juros.

boleto_interest[days]

dias após a expiração do boleto o juros deve ser cobrado.

boleto_interest[amount]

valor que será cobrado por dia de taxas de juros.

Limite para juros e multa

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

Os limites são:

Máximo de 1% ao mês de juros
Máximo de 2% ao mês de multa

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

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: "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
$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]'
  ]
]);
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.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 5 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.