# Coverage

Every institution on the [Boleto Management API](/docs/boleto/management-api) speaks the same API: one request to register a charge, one response shape, one set of statuses, one `boleto/updated` webhook. What differs between banks is how a **Boleto Connection** is established — what your customer has to provide, and whether they provide it to you or to the bank.

<Callout variant="warning" title="BETA">
The API is in BETA. Inter Empresas is the only institution available today; the rest of this page says what is coming and what will change when it does.
</Callout>

## Institutions

| Institution | Status | Authentication | Connect via |
|---|---|---|---|
| Inter Empresas | **Live** | Client ID, Client Secret, private key and certificate, created in Inter's Internet Banking — see the [Banco Inter Empresas tutorial](/docs/developer-tools/tutorials/inter-pj) | An existing Item ([POST /boleto-connections/from-item](/reference/boleto-connection-create-from-item)), or the credentials sent directly ([POST /boleto-connections](/reference/boleto-connection-create)) |
| Bradesco | In development | A Pluggy partner certificate (ours, shared) plus a one-time authorisation each company grants inside Bradesco's own environment, confirmed with a security key. Not possible through an API | A redirect to Bradesco and back; the flow is not live |
| Sandbox | Coming | None — issues boletos that look real and can be moved to any status on demand | Not yet: the Sandbox connector does not accept boleto connections today |

Connector ids, for [GET /connectors](/reference/connectors-list): Inter Empresas `225`, Bradesco `285`, Sandbox `600`.

## Inter Empresas

Inter is the reference implementation: everything below happens behind the same endpoints described in the [Boleto Management API](/docs/boleto/management-api) guide.

**Credentials.** Inter authenticates with four artifacts — a Client ID, a Client Secret, a private key and a certificate — created inside Inter's own Internet Banking. 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.

**Two ways to connect.** 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 the credentials directly is for when there is no Item to reuse.

```mermaid
graph TD
  A[Credentials from Inter] --> B[Connect through Pluggy Connect<br/>creates an Item]
  A --> C[Send credentials directly<br/>POST /boleto-connections]
  B --> D[POST /boleto-connections/from-item]
  C --> E[Boleto Connection]
  D --> E
```

**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` (typically `PIX` or `BOLETO`).

**Notifications.** Inter publishes the IP ranges its notifications originate from, and we only accept callbacks from those addresses. Nothing is required from you — what you receive is our own `boleto/updated` webhook, authenticated the same way as every other Pluggy webhook.

<Callout variant="info" title="Cancellations do not arrive by webhook">
A boleto you cancel through [POST /boletos/{id}/cancel](/reference/boleto-cancel) is marked `CANCELLED` immediately, as part of that call. 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.
</Callout>

**Worth knowing before you go live**

- **`nossoNumero` is Inter's, and its format is Inter's.** Do not parse it or assume a width; it will differ from what another institution returns 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.
- **Reconcile on `amountPaid`, not `amount`.** Discounts, fines and interest make them differ in both directions.

## Bradesco

Bradesco boleto issuing is not available yet. The model being built is described here so you can plan for it; the endpoints and the connection flow are not live, and the details may change as the integration is finished.

Every other institution on this API works the same way: your customer hands over credentials, we hold them, and we act with them. Bradesco separates **identifying the caller** from **authorising the action**:

```mermaid
graph TB
  subgraph "Once per company · inside Bradesco"
    A[Company's legal representative] -->|logs in at Bradesco| B[Accepts the terms]
    B -->|confirms with a security key| C[Authorisation recorded<br/>Pluggy may act for this CNPJ]
  end
  subgraph "Every request · server to server"
    D[Pluggy partner certificate] --> E[Issue a boleto for that CNPJ]
    C -.->|must already exist| E
  end
```

**The certificate** identifies Pluggy as the partner. It is ours, not your customer's, and it is the same certificate for every company we act for — there is no per-customer certificate to collect, install or renew.

**The authorisation** is granted once per company, by that company, inside Bradesco's own environment. Bradesco has confirmed this cannot be done through an API: the person authorising logs in at Bradesco, accepts the terms and confirms with a security key generated on their own device. We never see the password, the key, or the terms being signed. Without the authorisation, the certificate alone issues nothing; without the certificate, the authorisation is unusable.

**What this means for your onboarding.** Connecting a Bradesco account will involve a redirect: your customer leaves your interface, authorises at Bradesco, and returns. That is a different shape from the credential form used for Inter, and it introduces a state a credentials-only flow never has — a connection that exists but is not yet usable. Worth designing for now if Bradesco is on your roadmap.

**Still being settled with Bradesco:** the exact contract of the callback that confirms an authorisation; whether an authorisation expires, and whether revoking it inside Bradesco produces any notification; the onboarding path for companies that are not already Bradesco account holders; how a company with several CNPJs authorises for all of them.

## Sandbox

Testing a boleto integration against a real bank is slow and partly impossible: you need a business account, a real payer willing to pay a real charge, and for anything involving a due date you would have to wait for the date to arrive. The Sandbox connector is meant to remove all of that — boletos that look real, moved to any status on demand, firing the same webhooks a real bank would.

It is not available yet: the Sandbox connector does not accept boleto connections today. When it does, its boletos will carry a correctly shaped digitable line, barcode and PIX payload so your parsing and rendering are exercised, but they will **not** be valid payment instruments — nothing issued there can be paid at a real bank.

<Callout variant="info" title="What this page does not cover">
The request and response shapes, the status lifecycle and the webhook are the same for every institution and are documented once, in the [Boleto Management API](/docs/boleto/management-api) guide. This page only covers what differs: who is live, and how each bank lets us act for your customer.
</Callout>