Home
Start typing to search…

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

AccountId

Para a realização das requisições da API de boletos, é necessário que tenha em mãos o dado accountId. Na prática, este campo é uma concatenação dos dados da sua conta, seguindo o formato CNPJ+código bancário do BTG+agência+número da conta.

Este dado pode, e deve, ser obtido por meio de uma requisição na API de saldo e extrato Consultar dados das contas

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.

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.

Fluxo de atualização

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

Fluxo de vencimento

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

Boleto Fluxo-3

Eventos de webhook

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

Os payloads disponíveis abaixo representam o conteúdo do campo data, seguindo o formato do envio descrito em Eventos.

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

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

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

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

{
  "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-24T20:08:38.783Z", //Representa a data de crédito em conta. Segue a regra do D+1
    "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

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