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:

Escopo	Descrição
`empresas.btgpactual.com/bank-slips`	Permite criação e consulta de boletos.
`empresas.btgpactual.com/bank-slips.readonly`	Permite consulta de boletos e recebimento de webhooks.

Dicionário de Termos

Termos	Descrição
accountId	Id da conta na qual o boleto será emitido
arrears	Juros
penalty	Multa
paidAt	Dia em que o boleto foi pago
settledAt	Dia em que o boleto foi liquidado(D + 1 aplicável)
dueDate	Data de vencimento do boleto. Após esta data, multas e juros são aplicados
overDueDate	Data limite para pagamento do boleto. Após esta data, o boleto torna-se inválido
description	Campo de descrição da cobrança. Aceita até 300 caractéres.

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.

Especificidades

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

Juros pencentuais

O campo de juros na opção percentual é cobrado diariamente após o vencimento da cobrança, mas o valor percentual deve ser configurado em relação ao quanto se deseja cobrar mensalmente.

Por exemplo, se você deseja cobrar 0.03% de juros ao dia, deve-se realizar o post com o valor pencentual de 1%.

{
 //restante do payload do boleto
	"interests": {
    "arrears": {
      "type": "PERCENTAGE",
      "value": 1
    }
	},
	//restante do payload do boleto
}

Vale ressaltar que o juros é cobrado por dias corridos, então seriam acrescidos 0,03% de juros mesmo em fins de semana e feriados.

Status de boletos

Um boleto pode ter diversos status:

Status	Descrição
CREATED	Boleto emitido
PAID	Boleto pago
CANCELED	Boleto cancelado
EXPIRED	Boleto vencido
PROCESSING	Boleto em processamento
FAILED	Falha na emissão do boleto
UPDATED	Boleto atualizado
UPDATING	Boleto em atualização
CANCEL_FAILED	Falha no cancelamento do boleto
RETURNED	Boleto estornado
CANCELING	Boleto 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.

Eventos de webhook

A API de Boletos disponibiliza os seguintes eventos de webhook:

Identificação do Evento	Descrição
`bank-slips.failed`	Falha ao criar boleto
`bank-slips.updated`	Boleto atualizado
`bank-slips.update_failed`	Falha ao atualizar boleto
`bank-slips.canceled`	Boleto cancelado
`bank-slips.cancel_failed`	Falha ao cancelar boleto
`bank-slips.paid`	Boleto pago
`bank-slips.reversed`	Boleto 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

{
    "bankSlipId": "241f9999-9999-45cc-95e0-ae7b39999cd5",
    "correlationId": "rrt-8307999999999999999-b-gsa1-999999-999999-999",
    "status": "PAID",
    "barCode": "20899990800000109900009999099999999999989999",
    "digitableLine": "20890001999909999999999999999999999990099999999",
    "payee": {
        "accountId": "39999990000999-208-1-009999999",
        "taxId": "99999990000999",
        "bankCode": "208",
        "branchCode": "50",
        "number": "009999999"
    },
    "payer": {
        "name": "NAME",
        "taxId": "09999999999"
    },
    "ourNumber": "09999990999899989",
    "referenceNumber": "99999999",
    "amount": 109.9,
    "dueDate": "2025-06-10",
    "amountPaid": 99.9,
    "paymentMethod": "QRCODE",
    "paidAt": "2025-06-05",
    "pixInfo": {
        "emv": "00099999029999999999br.gov.bcb.pix2574api.developer.btgpactual.com/v1/p/v2/cobv/fe2e801a3f9d491caff548096e7fee3e5204653353999969999BR9999EXEMPLOS WEBHOOK61089999999962070503***630490D8",
        "key": "f7399999-3a03-9999-8a03-2c0fcd0c60f1",
        "txId": "46bfae68be9999999f999993abc5eeb61",
        "emvUrl": "https://static.empresas.btgpactual.com/bank-slip-pix/999999cee-08c2-478c-b7b8-e99999999999.png"
    },
    "overDueDate": "2025-06-10",
    "interests": {
        "arrears": {
            "value": 1,
            "type": "PERCENTAGE",
            "dueDate": "2025-06-11T00:00:00.000Z"
        },
        "penalty": {
            "value": 2,
            "type": "PERCENTAGE",
            "dueDate": "2025-06-11T00:00:00.000Z"
        }
    },
    "discounts": [
        {
            "value": 10,
            "type": "FIXED_VALUE",
            "dueDate": null
        }
    ],
    "settledAt": "2025-06-05T09:26:33.690Z"
}

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