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!

Introduction

To start using this API, we first need to create a Boleto Connection: a set of credentials that can manage boletos in an Institution.

We already solved the issue of connecting bank accounts with the concept of Items, which are used for data collection. They can also be used to create Boleto Connections (if their permission settings allow it). You could also create a boleto connection by sending raw credentials.

Using our Boleto Connection, we can create, get and cancel Boletos. We can also use webhooks to be notified when they are paid or expired. Let's look at the steps to do this!

 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 from the Item, by sending its ID

   POST /boleto-connection/from-item (request)

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

7. Copy the Boleto Connection ID from the response:

   POST /boleto-connection/from-item (response)

   {
     "id": "dc3537ad-13b4-4770-b248-e4578983899c",
     "connectorId": 225,
     "createdAt": "2023-01-01T00:00:00.000Z",
     "updatedAt": "2023-01-01T00:00:00.000Z"
   }
   

8. Now, create a Boleto for that Boleto Connection:

   POST /boletos (request)

   {
       "boletoConnectionId": "{YOUR-BOLETO-CONNECTION-ID}",
       "boleto": {
           "seuNumero": "1234567891",
           "amount": 2.5,
           "dueDate": "2025-03-01",
           "payer": {
               "taxNumber": "1234567890",
               "name": "Example name",
               "addressState": "SP",
               "addressZipCode": "01239030",
               "addressCity": "Não informado", // Optional
               "addressStreet": "Não informado"  // Optional
           }
       }
   }
   

9. You will get a response like this:

   POST /boletos (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
   }
   

10. 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, 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 the updated Boleto. When it is paid, the Boleto will have changed status to PAID, and the amountPaid and paymentOriginfields will be present:

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