Guias
These docs are for v1.2. Click to read the latest docs for v1.4.

Boletos

Gere boletos únicos, parcelados ou em lote com a API de Boletos

Suggest Edits

A API de boletos permite que você crie boletos únicos, parcelados e em lote para um ou múltiplos clientes, assim como a assinatura de eventos de boletos. Com esta API, você pode criar boletos com códigos de barras e QR codes para pagamento por Pix.

Um boletos tem três participantes:

  • O cedente ou beneficiário, que vendeu um produto ou serviço e emitiu o boleto.
  • O sacado, que vai pagar o boleto.
  • O sacador avalista, que emite o boleto para outra empresa.

Para emitir um boleto, apenas as informações do sacado são necessárias.

*Só é possível emitir boletos em nome da sua empresa.

*O formato para inserir quantias é 0.10.

Casos de Uso

  • Usar boletos do BTG Empresas como meio de pagamento.
  • Criar boletos a partir de um sistema de gestão empresarial.
  • Integrar com sistemas de contas a receber.
  • Aplicativos móveis com emissão e gerenciamento de boletos.

Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Boletos deve ser gerado usando o Authorization Code.

O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário escolher um dos seguintes escopos:

EscopoDescrição
empresas.btgpactual.com/bank-slipsPermite criação e consulta de boletos.
empresas.btgpactual.com/bank-slips.readonlyPermite consulta de boletos e recebimento de webhooks.

Recursos Disponíveis

Com a API de Boletos, você pode:

  • Criar boletos BTG Empresas personalizados para seus clientes, com opções de parcelamento, criação em lote e pagamento via Pix.
  • Atualizar informações em boletos como valor, data de vencimento, multas e juros.
  • Organizar boletos por data de criação, vencimento ou pagamento, além de status e pagador.

Os recursos da API de Boletos estão disponíveis no API Reference.

📘

API Reference

Boletos API

Campo ourNumber

Você pode definir até 20 dígitos do boleto no campo ourNumber. Pode-se utilizar qualquer código, desde que não seja o mesmo de um boleto apto para pagamento. Caso o campo esteja em branco, os dígitos do boleto serão gerados automaticamente.

Status de boletos

Um boleto pode ter diversos status:

StatusDescrição
CREATEDBoleto emitido
PAIDBoleto pago
CANCELEDBoleto cancelado
EXPIREDBoleto vencido
PROCESSINGBoleto em processamento
FAILEDFalha na emissão do boleto
UPDATEDBoleto atualizado
UPDATINGBoleto em atualização
CANCEL_FAILEDFalha no cancelamento do boleto
RETURNEDBoleto estornado
CANCELINGBoleto em cancelamento

Os status seguem os seguintes fluxos:

Fluxo normal

Um boleto é emitido e pago, podendo ser cancelado depois da emissão.

Boleto Fluxo-1

Fluxo de atualização

Um boleto emitido é atualizado, podendo ser cancelado após a atualização.

Boleto Fluxo-2

Fluxo de vencimento

Um boleto emitido perde a validade, podendo ser pago ou atualizado.

Boleto Fluxo-3

Eventos

A API de Boletos disponibiliza os seguintes eventos de webhook:

Identificação do EventoDescrição
bank-slips.failedFalha ao criar boleto
bank-slips.updatedBoleto atualizado
bank-slips.update_failedFalha ao atualizar boleto
bank-slips.canceledBoleto cancelado
bank-slips.cancel_failedFalha ao cancelar boleto
bank-slips.paidBoleto pago
bank-slips.reversedBoleto estornado*

*No caso de boleto estornado, o boleto não assumirá o status PAID. Haverá o disparo do evento de liquidação e depois haverá um de falha na liquidação. Neste cenário, o boleto se mantém em aberto e há o evento de bank-slips.reversed.

bank-slips.created

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.created",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1123452999999616503-a-gsa1-16666-27479025-277",
    "status": "CREATED",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001",
      "taxId": "123412412",
      "bankCode": "208",
      "branchCode": "50",
      "number": "213424214"
    },
    "payer": {
      "name": "Pagador",
      "taxId": "1000000000000"
    },
    "amount": 39.27,
    "dueDate": "2023-04-10",
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
  }
}

bank-slips.created(bolepix)

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.created",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1123452999999616503-a-gsa1-16666-27479025-277",
    "status": "CREATED",
    "barCode": "20000000000000000000000000000000000000000",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001",
      "taxId": "123412412",
      "bankCode": "208",
      "branchCode": "50",
      "number": "213424214"
    },
    "payer": {
      "name": "Pagador",
      "taxId": "1000000000000"
    },
    "amount": 39.27,
    "dueDate": "2023-04-10",
    "pixInfo": {
    "emv":"012342012345678967774br.gov.bcb.pix4444api.developer.btgpactual.com/v1/p/v2/cobv/333b10b777724ae081c52d4jjjja558052046533530398777777905VECHI6009SAO PAULO61080457777362888803\*\*\*77543EE5",
    "emvUrl": "https://static.empresas.btgpactual.com/bank-slip-pix/e123412341234fbsdfb1324.png",
    "key": "12345678-1111-5555-a3a7-d8812712345jjjj",
    "txId": "5b7777jjjjfjjjj7ae1111cb2ff407c7"
		},
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
  }

bank-slips.updated

Boleto atualizado.

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.updated",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
    "status": "UPDATED",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001"
    },
    "payer": {
      "name": "PAYER LTDA",
      "taxId": "1000000000000"
    },
    "amount": 39.27,
    "dueDate": "2023-04-10",
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
  }
}

bank-slips.canceled


Boleto cancelado. 

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.canceled",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
    "status": "CANCELED",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001"
    },
    "payer": {
      "name": "PAYER LTDA",
      "taxId": "1000000000000"
    },
    "amount": 3927,
    "dueDate": "2023-04-10",
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
    
  }
}

bank-slips.canceled(bolepix)

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.canceled",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
    "status": "CANCELED",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001"
    },
    "payer": {
      "name": "PAYER LTDA",
      "taxId": "1000000000000"
    },
    "amount": 3927,
    "dueDate": "2023-04-10",
    "pixInfo": {  
   		"emv":"012342012345678967774br.gov.bcb.pix4444api.developer.btgpactual.com/v1/p/v2/cobv/333b10b777724ae081c52d4jjjja558052046533530398777777905VECHI6009SAO PAULO61080457777362888803\*\*\*77543EE5",  
   		"key": "12345678-1111-5555-a3a7-d8812712345jjjj",  
   	  "txId": "5b7777jjjjfjjjj7ae1111cb2ff407c7"  
		},
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
  }
}

bank-slips.cancel_failed

Falha ao cancelar boleto. 

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.cancel_failed",
  "data": {
    "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
    "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
    "status": "CANCEL_FAILED",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001"
    },
    "payer": {
      "name": "PAYER LTDA",
      "taxId": "1000000000000"
    },
    "amount": 3927,
    "dueDate": "2023-04-10"
  }
}

bank-slips.paid

Boleto pago.

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.paid",
  "data": {
    "payee": {
      "taxId": "00000000000",
      "number": "111111111",
      "bankCode": "208",
      "accountId": "0000000000-208-50-1111111",
      "branchCode": "50"
    },
    "payer": {
      "name": "Nome do pagador",
      "taxId": "2222222222222"
    },
    "amount": 1,
    "paidAt": "2024-03-23",
    "status": "PAID",
    "barCode": "111111111111111111111111111111",
    "dueDate": "2024-04-01",
    "pixInfo": {
      "emv": "11111111111111111111111br.gov.bcb.pix1111api.developer.btgpactual.com/v1/p/v2/cobv/teste",
      "key": "pixkey_teste",
      "txId": "44444444444440"
    },
    "settledAt": "2024-03-23T20:08:38.783Z",
    "amountPaid": 0.01,
    "bankSlipId": "5555555555555b55555f55555",
    "correlationId": "doc-teste",
    "digitableLine": "555555555555dddddddfffff555555",
    "paymentMethod": "BARCODE",
    "interests": {
      "arrears": {
        "value": 0.33,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      },
      "penalty": {
        "value": 2,
        "type": "PERCENTAGE",
        "dueDate": "2024-07-09T00:00:00.000Z"
      }
    },
    "discounts": []
  }
}

bank-slips.failed

Falha ao criar boleto.

{
  "webhookId": "10939418j032109-20308g-03219423dsv89",
  "event": "bank-slips.failed",
  "data": {
    "bankSlipId": "863532c6-0000-0000-0000-601e34bedc86",
    "correlationId": "2385751161",
    "ourNumber":"11111111111",
    "referenceNumber":"123",
    "status": "FAILED",
    "barCode": "20000000000000000000000000000000000000000",
    "digitableLine": "20000000000000000000000000000000000000000",
    "payee": {
      "accountId": "0000000000009-008-00-00000001"
   
    },
    "payer": {
      "name": "PAYER LTDA",
      "taxId": "1000000000000"
    },
    "amount": 392.7,
    "dueDate": "2023-04-10"
  }
}

Updated 5 months ago