Pluggy Node.js SDK (pluggy-sdk)

Official Node.js/TypeScript SDK for the Pluggy API.

• API Docs: https://docs.pluggy.ai
• Base URL: https://api.pluggy.ai/

Installation

npm install pluggy-sdk

Requirements

• Node.js: >=12.0.0

Quickstart

import{PluggyClient}from'pluggy-sdk'constclient=newPluggyClient({clientId: process.env.PLUGGY_CLIENT_ID!,clientSecret: process.env.PLUGGY_CLIENT_SECRET!,})asyncfunctionmain(){// Example: list connectorsconstconnectors=awaitclient.fetchConnectors()console.log('connectors',connectors.length)}main().catch((err)=>{console.error(err)process.exitCode=1})

Authentication

The SDK uses your Pluggy credentials:

• PLUGGY_CLIENT_ID
• PLUGGY_CLIENT_SECRET

If you don’t have credentials yet, generate them in the Pluggy dashboard and refer to the docs for environment setup.

Core API examples

Create a Connect Token

import{PluggyClient}from'pluggy-sdk'constclient=newPluggyClient({clientId: process.env.PLUGGY_CLIENT_ID!,clientSecret: process.env.PLUGGY_CLIENT_SECRET!,})constconnectToken=awaitclient.createConnectToken({// Tip: pass the fields required by your integration// (e.g. options, itemId, connectorId, etc.)})

Items

// Create an itemconstitem=awaitclient.createItem({connectorId: 123,parameters: {// connector-specific parameters},})// Fetch an itemconstfetched=awaitclient.fetchItem(item.id)// Update item MFA (when required)awaitclient.updateItemMFA(item.id,{// mfa payload from Pluggy})

Accounts and transactions (with pagination)

Transactions use cursor-based pagination against GET /v2/transactions. The SDK exposes two helpers:

• fetchTransactionsCursor(accountId, options) — fetch a single page and the cursor to the next one.
• fetchAllTransactions(accountId, options) — iterate through every page and return the full list.

constaccounts=awaitclient.fetchAccounts(item.id)constaccount=accounts.results[0]// Single page (returns { results, next })constpage=awaitclient.fetchTransactionsCursor(account.id,{dateFrom: '2024-01-01',})// Manual pagination: follow the cursor until `next` is nullletcursor=page.nextwhile(cursor){consturl=newURL(cursor)constafter=url.searchParams.get('after')!constnext=awaitclient.fetchTransactionsCursor(account.id,{dateFrom: '2024-01-01',
after,})// ...do something with next.resultscursor=next.next}// Or fetch all transactions in one callconstall=awaitclient.fetchAllTransactions(account.id,{dateFrom: '2024-01-01',})

Deprecation note: the legacy page-based fetchTransactions(accountId, options) method (GET /transactions) is @deprecated and will be removed in a future major release. Migrate to fetchTransactionsCursor / fetchAllTransactions — the cursor endpoint is more stable for long lists and supports the full filter set (dateTo, ids, etc.).

Webhooks

constwebhook=awaitclient.createWebhook({url: 'https://example.com/webhooks/pluggy',event: 'item.created',})constwebhooks=awaitclient.fetchWebhooks()awaitclient.deleteWebhook(webhook.id)

Payments API examples

Use PluggyPaymentsClient for payment initiation features.

import{PluggyPaymentsClient}from'pluggy-sdk'constpayments=newPluggyPaymentsClient({clientId: process.env.PLUGGY_CLIENT_ID!,clientSecret: process.env.PLUGGY_CLIENT_SECRET!,})

Create and fetch a payment recipient

constrecipient=awaitpayments.createPaymentRecipient({// recipient payload (PIX / bank account details, etc.)})constfetched=awaitpayments.fetchPaymentRecipient(recipient.id)

Create a payment request

constrequest=awaitpayments.createPaymentRequest({// payment request payload})

Error handling

The SDK throws on non-2xx responses. Recommended pattern:

try{constitem=awaitclient.fetchItem('item_id')console.log(item)}catch(err){// Surface the error message and/or response details in your app logsconsole.error(err)}

TypeScript

This package is written in TypeScript and ships with types. You can import types from the package directly:

importtype{Item,Transaction}from'pluggy-sdk'

Support

• API documentation: https://docs.pluggy.ai
• OpenAPI spec: https://api.pluggy.ai/oas3.json

License

MIT