With our Boleto Management API, you can quickly create a Boleto and receive payment notifications for it, allowing you to automate your entire billing process by leveraging our direct integrations with banks.

We expose a single, uniform API to manage Boletos, while behind the scenes we take care of things like secure authentication and the different details of integrating with each bank.

📘

BETA feature

This feature is currently BETA, with support for Inter Empresas. We are currently working on integrating with many others!

 Getting started (Inter example)

1. First, create a Pluggy Item by connecting your account. You can do this from Dashboard -> any application -> Preview in Demo.

   

2. Select Inter Empresas.

   

3. From the Inter Empresas website, create your set of integration credentials to log in. Make sure to enable Boleto and Extrato permissions.

   

4. Copy the created Item's ID

   

5. Obtain an API key from our Auth endpoint, using the credentials of your application from the first step.

   POST /token

   {
     "clientId": "{YOUR-CLIENT-ID}",
     "clientSecret": "{YOUR-CLIENT-SECRET}"
   }
   

6. Create a Boleto Connection, sending the Item ID

   POST /boleto-connection/from-item

       {  
        "itemId": "{YOUR-ITEM-ID}"  
      }
   

7. Now, create a Boleto

   POST /boletos

   {
       "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
       "boleto": {
           "seuNumero": "1234567891",
           "amount": 2.5,
           "dueDate": "2025-03-01",
           "payer": {
               "taxNumber": "1234567890",
               "name": "Example name",
               "addressState": "SP",
               "addressZipCode": "01239030"
           }
       }
   }
   

8. You will get a response like this:

   Boleto response

   {
       "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
       "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
       "amount": 2.5,
       "status": "OPEN",
       "seuNumero": "1234567891",
       "dueDate": "2025-03-01",
       "payer": {
           "ddd": "",
           "name": "Example name",
           "email": "",
           "taxNumber": "1234567890",
           "personType": "FISICA",
           "addressCity": "Não informado",
           "phoneNumber": "",
           "addressState": "SP",
           "addressNumber": "",
           "addressStreet": "Não informado",
           "addressZipCode": "01239030",
           "addressComplement": "",
           "addressNeighborhood": ""
       },
       "pixQr": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20",
       "digitableLine": "01120001161117012359902128847071234570777000110",
       "nossoNumero": "10000004701",
       "barcode": "01120001161117012359902128847071234570",
       "amountPaid": null,
       "paymentOrigin": null
   }
   

9. All set! You can now cancel the Boleto with POST /boletos/{id}/cancel to clean up.

Payment notifications

To receive a notification when a Boleto is paid or expired, set up the boleto/updated webhook, and you will receive an event like so:

{
  "boletoId": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "boleto/updated"
}

Upon receiving the event, you can do a GET /boleto/{id} to see what information has been updated. For example, here, the Boleto now has status PAID, and the amountPaid and paymentOriginfields are now filled in:

{
    "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
    "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
    "amount": 2.5,
    "status": "PAID",
    "seuNumero": "1234567891",
    "dueDate": "2025-03-01",
    "payer": {
        "ddd": "",
        "name": "Example name",
        "email": "",
        "taxNumber": "1234567890",
        "personType": "FISICA",
        "addressCity": "Não informado",
        "phoneNumber": "",
        "addressState": "SP",
        "addressNumber": "",
        "addressStreet": "Não informado",
        "addressZipCode": "01239030",
        "addressComplement": "",
        "addressNeighborhood": ""
    },
    "pixQr": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20",
    "digitableLine": "01120001161117012359902128847071234570777000110",
    "nossoNumero": "10000004701",
    "barcode": "01120001161117012359902128847071234570",
    "amountPaid": 2.5,
    "paymentOrigin": "PIX"
}