# pluggy-connect-sdk > Pluggy Connect SDK Latest version **2.14.2** (published 2026-08-13) · MIT license · 0 weekly downloads ## Install ```sh npm install pluggy-connect-sdk pnpm add pluggy-connect-sdk yarn add pluggy-connect-sdk bun add pluggy-connect-sdk ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.14.2 | | Published | 2026-08-13 | | First published | 2020-12-19 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 146.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Pluggy Engineering | | Maintainers | fmiras, tmilar, gpanga, nicolasmontone | ## Links - npm: https://www.npmjs.com/package/pluggy-connect-sdk - Repository: https://github.com/pluggyai/pluggy-connect - Homepage: https://github.com/pluggyai/pluggy-connect#readme - Issues: https://github.com/pluggyai/pluggy-connect/issues - npm.io page: https://npm.io/package/pluggy-connect-sdk ## Dependencies (2) - [zoid](https://npm.io/package/zoid.md) 9.0.63 - [jwt-decode](https://npm.io/package/jwt-decode.md) 4.0.0 ## Recent versions - 2.14.2 (latest) — 2026-08-13 - 2.4.1-alpha.2 (alpha) — 2023-01-18 - 0.1.0-RC.1 (next) — 2021-03-23 - 2.14.1 — 2026-07-30 - 2.14.0 — 2026-07-29 - 2.13.0 — 2025-12-01 - 2.12.0 — 2025-12-01 - 2.11.0 — 2025-11-14 - 2.10.1 — 2025-11-14 - 2.10.0 — 2025-11-14 - 2.9.2 — 2025-01-27 - 2.9.1 — 2024-12-11 - 2.9.0 — 2024-12-11 - 2.8.2 — 2024-11-19 - 2.8.1 — 2023-09-25 - … 46 more at https://npm.io/package/pluggy-connect-sdk/versions ## README # Pluggy Connect SDK Plain Javascript Wrapper for our [Pluggy Connect](https://docs.pluggy.ai/#pluggy-connect-widget) widget. ## Setup Using `npm`: ```shell npm install pluggy-connect-sdk ``` Using `yarn`: ```shell yarn add -S pluggy-connect-sdk ``` Importing directly as an HTML ` ``` Additionally, you can refer to the `latest` release by referencing the URL like so: ```html ``` ## Usage The following is a minimal usage example: ```js import PluggyConnect from 'pluggy-connect-sdk'; // First, configure the instance to your needs const pluggyConnect = new PluggyConnect({ connectToken: 'qwerty123...', // Your Pluggy Connect Token (required) includeSandbox: false, // if set to 'true', sandbox connectors will be included onSuccess: (itemData) => { // Connection success callback handler console.log('Yay! Pluggy connect success!', itemData); }, onError: (error) => { // Error callback handler console.error('Whoops! Pluggy Connect error... ', error); }, }); // Then, open it pluggyConnect.init(); ``` ## API ### init Opens the Pluggy Connect widget on a modal. Returns a Promise that resolves when it has been rendered, or throws if it has failed. ### show If Pluggy Connect widget modal was hidden, this method will display it. Returns a Promise that resolves when it has been shown, or throws if instance reference does not exist. ### hide If Pluggy Connect widget modal is visible, this method will minimize/hide it, without closing it. Returns a Promise that resolves when it has been hidden, or throws if instance reference does not exist. ### destroy Manually destroys the current PluggyConnect instance. Useful to cleanup all connection resources. Note: usually this wouldn't be recommended, the instance should be created once and open/close it as needed. Returns a Promise that resolves when destroyed, or throws if it has failed for some reason. ## Configurations The following properties are available for configuration. For more info, please see our [documentation](https://docs.pluggy.ai/#pluggy-connect-widget) to find the most up-to-date details. | Property | Description | Required? | Type | Default | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `connectToken` | Your Pluggy Connect token, which will be used to access the API. | ✅ | `string` | N/A | | `includeSandbox` | Whether to display Sandbox connectors in the Connector selection step (not intended for production use) | 🔲 | `boolean` | `false` | | `allowConnectInBackground` | If true, Connect can be minimized by the user to continue the connection with the component hidden | 🔲 | `boolean` | `false` | | `allowFullscreen` | If set to false, Connect won't be displayed as fullscreen on small/mobile screens, it will be displayed as a modal instead. | 🔲 | `boolean` | `true` | | `updateItem` | Item id to update. If specified, the modal will display directly the credentials form of the item to be updated. | 🔲 | `string` | N/A | | `connectorTypes` | List of [Connector Types](https://docs.pluggy.ai/docs/connectors-coverage). If defined, only Connectors of the specified connector types will be listed. | 🔲 | `ConnectorType[]` | N/A | | `connectorIds` | List of [Connector IDs](https://docs.pluggy.ai/docs/connectors-coverage). If defined, only Connectors of the specified connector IDs will be listed. | 🔲 | `number[]` | N/A | | `countries` | List of country codes ([ISO-3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). If defined, only Connectors of the specified countries will be listed. | 🔲 | `CountryCode[]` | N/A | | `products` | If defined, only the products specified in this array will be executed in the item creation (in order to be executed, you should have them enabled in your team subscription). | 🔲 | `ProductType[]` | N/A | | `selectedConnectorId` | If specified and the Connector is present, after accepting terms, the widget will navigate to this Connector login form directly, skipping connectors selection step. | 🔲 | `number` | N/A | | `language` | Language (2-letter ISO code string), used to display the widget. If not specified, or if the selected language is not supported, the default `'pt'` will be used. | 🔲 | `string` | `'pt'` | | `theme` | Theme to use for displaying the UI. Can be 'light' or 'dark'. Defaults to 'light' | 🔲 | `'light' `|` 'dark'` | `'light'` | | `openFinanceParameters` | Object with CPF and CNPJ for Open Finance connectors only, the form will be pre-filled with these values. Contains optional `cpf` and `cnpj` string fields. | 🔲 | `{ cpf?: string; cnpj?: string }` | N/A | | `forceOauthInBrowser` | If set to `true`, OAuth URLs will always open in the system browser instead of a webview. This helps avoid webview-related issues. The prop takes precedence over the API config value. | 🔲 | `boolean` | `false` | | `forceAskForCredentials` | If set to `true`, the widget will always prompt for credentials when updating an item, even if the system would normally attempt to update automatically. | 🔲 | `boolean` | `false` | | `connectorSortAlphabetically` | If set to `true`, connectors will be sorted alphabetically (A-Z) instead of by usage. | 🔲 | `boolean` | `false` | | `onSuccess` | Function to execute when an [Item](https://docs.pluggy.ai/docs/item) has been created/updated successfully. | 🔲 | `(data: { item: Item }) => void `|` Promise` | No op | | `onError` | Function to execute on a general error loading the widget, or when an Item creation/update status has not been successful. | 🔲 | `(error: { message: string; data?: { item: Item } }) => void `|` Promise` | No op | | `onOpen` | Function to execute when the widget modal has been opened. | 🔲 | `() => void `|` Promise` | No op | | `onClose` | Function to execute when the widget modal has been closed. | 🔲 | `() => void `|` Promise` | No op | | `onEvent` | Function to execute to handle custom user interaction events. See the [docs](https://docs.pluggy.ai/docs/environments-and-configurations) for more info. | 🔲 | **Since v2:**
`(payload: ConnectEventPayload) => void `|` Promise`
**1.x**:
`(event: string, metadata: { timestamp: number }) => void` | No op | ### onEvent This callback allows handling more specific events. The property `event` inside the `payload` param of the onEvent callback, is the name of the current event triggered. The available events that can be handled through this method are: | Event name | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `'SUBMITTED_CONSENT'` | User has confirmed terms & privacy consent on the first Welcome screen. | | `'SELECTED_INSTITUTION'` | User has selected an institution to connect to, or has deselected it (ie. navigated back to previous step). | | `'SUBMITTED_LOGIN'` | User has submitted credentials to create the connection Item. | | `'SUBMITTED_MFA'` | User has submitted an extra parameter that has been requested by the institution to connect. | | `'LOGIN_SUCCESS'` | User has submitted credentials to create the connection Item successfully. | | `'LOGIN_MFA_SUCCESS'` | User has submitted an extra parameter that has been requested by the institution to connect successfully. | | `'LOGIN_STEP_COMPLETED'` | Successful completion of the login. User effectively logged in to the institution. | | `'ITEM_RESPONSE'` | Called every time the Item object is retrieved from Pluggy API, either when just created, updated, or each time it's retrieved to poll it's connection/execution status. | `payload` object has a property timestamp and some events extra data: `'SELECTED_INSTITUTION'` has the connector property which is the connector selected by the user. `'LOGIN_SUCCESS' | 'LOGIN_MFA_SUCCESS' | 'LOGIN_STEP_COMPLETED' | 'ITEM_RESPONSE'` events have the item property which is the item data related to the current connection. Full `event` parameter type definition is: ```ts type ConnectEventPayload = { timestamp: number; } & ( | { event: 'SUBMITTED_CONSENT' | 'SUBMITTED_LOGIN' | 'SUBMITTED_MFA'; } | { event: 'SELECTED_INSTITUTION'; connector: Connector | null; } | { event: 'LOGIN_SUCCESS' | 'LOGIN_MFA_SUCCESS' | 'LOGIN_STEP_COMPLETED' | 'ITEM_RESPONSE'; item: Item; } ); ``` ## Quickstart example You can find a fully working functional example in our [Quickstarts](https://github.com/pluggyai/quickstart/tree/master/connect) repo, in the [/html](https://github.com/pluggyai/quickstart/tree/master/connect/html) folder. Feel free to clone or fork it to quickly get started with your application! ## Typescript Support This project was built using Typescript so all typings are natively built-in. However, for up-to-date Pluggy API typings, you'll need to install `pluggy-js` in your project as well, either as a dev or prod dependency. ```shell npm install pluggy-js ``` ## Cordova Support If your project is using Cordova (ie. Ionic Framework), be sure to also install the `cordova-plugin-inappbrowser` plugin. This is necessary for links to be opened properly in the system browser, and for Oauth redirects to work as expected, without blocking the main app frame. ```shell cordova plugin add cordova-plugin-inappbrowser ``` ## Issues We'll be glad if you report any issue you'd find in the [issues](https://github.com/pluggyai/pluggy-connect/issues) section. ## Contributing All contributions welcome! Feel free to submit your PR and tag any of the _Pluggyers_ for a quick review. --- _Source: https://npm.io/package/pluggy-connect-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._