Boletos

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

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 os 16 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 16 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
bank-slips.rejectedBoleto rejeitado

bank-slips.updated

Boleto atualizado.
*Boletos com QR Code não podem ser atualizados.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "UPDATED",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 39.27,
  "dueDate": "2023-04-10"
}

bank-slips.canceled

Boleto cancelado.

{
  "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"
}

bank-slips.cancel_failed

Falha ao cancelar boleto.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "CANCEL_FAILED",
  "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.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "PAID",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 39.27,
  "dueDate": "2023-04-10"
}

bank-slips.failed

Falha ao criar boleto.

{
    "bankSlipId": "863532c6-0000-0000-0000-601e34bedc86",
    "correlationId": "2385751161",
    "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"
}