Basic concepts#
What is an item?#
An item represents the connection between a user and a financial institution, together with all the data returned by that connection.
What is an application, and which types are available?#
An application is the pair of clientId and clientSecret keys used to reach the API. Handle them carefully: they are the only thing standing between the outside world and your data. You can create applications in both the Development and Production environments.
What is the difference between an apiKey and a connectToken?#
The apiKey grants access to the API. You obtain it from your Pluggy credentials (clientId and clientSecret) and it is valid for 2 hours.
The connectToken is the key used to open the Pluggy Connect widget — the graphical interface on top of the API. Getting a connectToken requires an apiKey first, and it lasts 30 minutes.
Connectors and financial institutions#
What is the difference between Pluggy connectors and Open Finance connectors?#
| Pluggy connectors (unregulated) | Open Finance connectors (regulated) | |
|---|---|---|
| Technology | Pluggy's own | Framework regulated by the Central Bank |
| Access | Direct to the financial institution | Through the user's consent |
| Data | As shown in the internet banking | Standardised and enriched |
For more detail, see Item.
How do I check which financial institutions are available?#
There are three ways to look up the available institutions (connectors):
- Documentation — Open Finance (regulated) and Pluggy connectors (unregulated).
- API —
GET /connectors. - Dashboard — the Customization tab.
Which institutions need a token to connect?#
The institutions that require a token are listed in Connectors coverage.
How do I enable connectors in my application?#
Open the Customization tab in the dashboard.
Can I skip the bank-selection step in the Pluggy Connect widget?#
Yes. The selectedConnectorId attribute shows only the connector you pre-select. See Environments and configurations.
Managing items and connections#
If a user connects the same account twice, are two different connections created?#
Yes. Every time the user gives consent — entering credentials on a Pluggy connector, or picking which data to share on an Open Finance one — a new connection is created with a new itemId. To avoid this, create the connection once and update that same itemId whenever you need fresher data.
There is also a setting that checks whether the account has been connected before: see avoiding duplicates.
How can I tell which of my users an itemId belongs to?#
Send the clientUserId field when the item is created, or when you open the Pluggy Connect widget. It takes any string you like; we recommend "name | email | cpf_or_cnpj". See the connect token options.
How do I revoke a consent (a connection)?#
Delete the corresponding item through the API. That ends the connection and removes the data associated with it.
Why did my itemId stop updating?#
The most common cause is hitting the institution's request limit, which happens when the same account is connected many times over.
Limit per CPF/CNPJ: this limit is shared across every itemId belonging to the same CPF or CNPJ. Once it is reached, transactions only resume updating the following month.
The item hit the limit — what can I do?#
The limit cannot be lifted within the current month. To keep it from happening again, avoid creating multiple connections for the same account: reuse the same itemId and update it when you need more recent data.
Can I list every item I have created at Pluggy?#
No. Listing items is not available for security reasons, so that no data can leak across clients.
Are new transactions on an account updated in real time?#
No. New transactions become available only after the connection is updated — see updating an item.
On Open Finance (regulated) connectors, new transactions can take up to 24h to become available.
How does automatic updating work?#
Pluggy can update your itemIds on a schedule — just ask through any of our channels. You can choose the hour the updates start; items are queued and updated according to available processing capacity, so nothing is overloaded.
Environments and production#
How do I go to production?#
Create a production application in the dashboard, under Applications, using Go to production. A production application matters because:
- automatic updating is available;
- there is no limit on the number of
itemIds; - there is no demo page, so no customer data is exposed.
Can I keep Development and Production separate? Does the client_id/secret change?#
Yes. Create the environments in the dashboard; each new environment gets its own clientId and clientSecret.
The Development environment is capped at 100 items.
Webhooks and events#
Which webhook events are available?#
The full list is in the webhooks reference.