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

Nosso número

Você pode definir os 16 dígitos do boleto no campo nosso número (ourNumber). Pode ser 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.

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-2070-4ce0-b496-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "UPDATED",
  "barCode": "20893929900003927000050013606201261603478710",
  "digitableLine": "20890050091360620126016034787107392990000392700",
  "payee": {
    "accountId": "44167119000129-208-50-003478711"
  },
  "payer": {
    "name": "JUBIABA PARTICIPACOES LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.canceled

Boleto cancelado. 

{
  "bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "CANCELED",
  "barCode": "20893929900003927000050013606201261603478710",
  "digitableLine": "20890050091360620126016034787107392990000392700",
  "payee": {
    "accountId": "44167119000129-208-50-003478711"
  },
  "payer": {
    "name": "JUBIABA PARTICIPACOES LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.cancel_failed

Falha ao cancelar boleto. 

{
  "bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "CANCEL_FAILED",
  "barCode": "20893929900003927000050013606201261603478710",
  "digitableLine": "20890050091360620126016034787107392990000392700",
  "payee": {
    "accountId": "44167119000129-208-50-003478711"
  },
  "payer": {
    "name": "JUBIABA PARTICIPACOES LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.paid

Boleto pago.

{
  "bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "PAID",
  "barCode": "20893929900003927000050013606201261603478710",
  "digitableLine": "20890050091360620126016034787107392990000392700",
  "payee": {
    "accountId": "44167119000129-208-50-003478711"
  },
  "payer": {
    "name": "JUBIABA PARTICIPACOES LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.failed

Falha ao criar boleto.

{

  "eventId": "bank-slips.failed",

  "metadataId": "46467854000183-208-50-004116558",

  "tenantId": "46467854000183",

  "message": {

    "bankSlipId": "863532c6-ff68-4dac-8989-601e34bedc86",

    "correlationId": "2385751161",

    "status": "FAILED",

    "barCode": "2089492810000012770005001000000001510000550",

    "digitableLine": "20890050091000000001751041165500092810000012770",

    "payee": {

      "accountId": "46467854000183-208-50-004116558"

    },

    "payer": {

      "name": "JUBIABA PARTICIPACOES LTDA",

      "taxId": "00000000000000001"

    },

    "amount": 127.7,

    "dueDate": "2023-03-06"

  }

}

Updated 13 days ago