Inter Empresas is the first institution available on the Boleto Management API, and the reference implementation: everything on this page happens behind the same endpoints described in the Boleto Management API guide.
Establishing a connection#
Inter authenticates with four artifacts — a Client ID, a Client Secret, a private key and a certificate — created inside Inter's own Internet Banking. The Banco Inter Empresas tutorial walks through producing them.
Enable the right permissions
When creating the integration at Inter, enable both Boleto and Extrato scopes. A credential missing the Boleto scope connects successfully and then fails on the first issue attempt, which is a confusing place to discover the problem.
There are two ways to turn those credentials into a connection:
Going through an Item is the better default when you already collect account data for the same customer: one connection, one set of credentials, and the customer authorises once. Sending credentials directly is for when there is no Item to reuse.
Several Boleto Connections on one Inter integration#
Inter accepts a single billing (cobrança) webhook per integration. We register one webhook that serves every Boleto Connection on that integration, and route each notification to the right boleto by Inter's own identifier for the charge. So one Client ID + Client Secret pair can back as many Boleto Connections as you need: another Pluggy application, another team, or a connection recreated after a deletion, whether you create it directly or from an Item.
Creating a connection on an integration that already carries our webhook simply keeps it in place. Boletos issued on earlier connections of the same integration, including connections you have since deleted, keep receiving their status updates.
The one case we do not touch is a billing webhook that another system configured on the integration (your own backend, an ERP, another provider). Replacing it would silently cut that system off, so creating the connection fails with:
Não foi possível criar a boleto connection: A integração já tem um webhook de cobrança configurado por outro sistema. Por favor, exclua esse webhook para criar uma Boleto Connection ou crie uma integração nova sem webhook.
To go ahead, either remove that webhook (Inter's DELETE /cobranca/v3/cobrancas/webhook, with that integration's credentials) once nothing depends on it, or create another integration at Inter for Pluggy, with its own Client ID, Client Secret and certificate, following the Banco Inter Empresas tutorial. Downloading a new certificate for the same integration does not help: the webhook belongs to the integration, not to the certificate.
How Inter reports a payment#
Inter notifies us, and we translate its vocabulary into the statuses the API exposes:
Inter situacao | Becomes |
|---|---|
RECEBIDO | PAID |
MARCADO_RECEBIDO | PAID |
ATRASADO | OVERDUE |
PROTESTO | PROTESTED |
A_RECEBER | ignored — the boleto is simply still open |
When a boleto becomes PAID, Inter also reports what was actually paid and how, which lands in amountPaid and paymentOrigin. paymentOrigin is typically PIX or BOLETO, reflecting how the payer chose to settle.
Cancellations do not arrive by webhook
A boleto you cancel through POST /boletos//cancelAPI is marked CANCELLED immediately, as part of that call. But a boleto cancelled directly inside Inter's own portal will not update on our side — that path produces no status change you can observe. If your operations team cancels boletos at Inter rather than through the API, treat our status as authoritative only for boletos cancelled through the API.
Authenticating the notifications#
Inter publishes the IP ranges its notifications originate from, and we only accept callbacks from those addresses. Nothing is required from you — the notification you receive is our own boleto/updated webhook, authenticated the same way as every other Pluggy webhook.
Worth knowing before you go live#
nossoNumerois Inter's, and its format is Inter's. Do not parse it or assume a width; it differs from what another institution will return for the same charge.- A late payment is normal. Inter accepts payment after the due date, so a boleto can go
OPEN → OVERDUE → PAID. Handlers that stop listening once a boleto is overdue miss real revenue. - Test the partial-payment path.
amountPaidcan be lower or higher thanamountonce discounts, fines or interest apply. The Sandbox produces it on demand: issue a boleto with an amount ending in,01and it is paid for half.