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'

const client = new PluggyClient({
  clientId: process.env.PLUGGY_CLIENT_ID!,
  clientSecret: process.env.PLUGGY_CLIENT_SECRET!,
})

async function main() {
  // Example: list connectors
  const connectors = await client.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'

const client = new PluggyClient({
  clientId: process.env.PLUGGY_CLIENT_ID!,
  clientSecret: process.env.PLUGGY_CLIENT_SECRET!,
})

const connectToken = await client.createConnectToken({
  // Tip: pass the fields required by your integration
  // (e.g. options, itemId, connectorId, etc.)
})

Items

// Create an item
const item = await client.createItem({
  connectorId: 123,
  parameters: {
    // connector-specific parameters
  },
})

// Fetch an item
const fetched = await client.fetchItem(item.id)

// Update item MFA (when required)
await client.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.

const accounts = await client.fetchAccounts(item.id)
const account = accounts.results[0]

// Single page (returns { results, next })
const page = await client.fetchTransactionsCursor(account.id, {
  dateFrom: '2024-01-01',
})

// Manual pagination: follow the cursor until `next` is null
let cursor = page.next
while (cursor) {
  const url = new URL(cursor)
  const after = url.searchParams.get('after')!
  const next = await client.fetchTransactionsCursor(account.id, {
    dateFrom: '2024-01-01',
    after,
  })
  // ...do something with next.results
  cursor = next.next
}

// Or fetch all transactions in one call
const all = await client.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

const webhook = await client.createWebhook({
  url: 'https://example.com/webhooks/pluggy',
  event: 'item.created',
})

const webhooks = await client.fetchWebhooks()

await client.deleteWebhook(webhook.id)

Payments API examples

Use PluggyPaymentsClient for payment initiation features.

import { PluggyPaymentsClient } from 'pluggy-sdk'

const payments = new PluggyPaymentsClient({
  clientId: process.env.PLUGGY_CLIENT_ID!,
  clientSecret: process.env.PLUGGY_CLIENT_SECRET!,
})

Create and fetch a payment recipient

const recipient = await payments.createPaymentRecipient({
  // recipient payload (PIX / bank account details, etc.)
})

const fetched = await payments.fetchPaymentRecipient(recipient.id)

Create a payment request

const request = await payments.createPaymentRequest({
  // payment request payload
})

Error handling

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

try {
  const item = await client.fetchItem('item_id')
  console.log(item)
} catch (err) {
  // Surface the error message and/or response details in your app logs
  console.error(err)
}

TypeScript

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

import type { Item, Transaction } from 'pluggy-sdk'

Support

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

License

MIT