Pluggy Integration

Comprehensive integration guide for Pluggy Open Finance API. Contains rules across 5 categories, prioritized by impact to guide accurate implementation.

When to Apply

Reference these guidelines when:

Setting up Pluggy SDK and authentication
Implementing the Connect Widget in frontend applications
Creating, updating, or managing Items (connections)
Handling MFA (Multi-Factor Authentication) flows
Configuring webhooks for real-time data sync
Managing API keys and tokens
Handling connection errors and edge cases

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Authentication	CRITICAL	`auth-`
2	Connect Widget	CRITICAL	`widget-`
3	Webhook Configuration	CRITICAL	`webhook-`
4	Item Lifecycle	HIGH	`item-`
5	Error Handling	MEDIUM	`error-`

How to Use

Read individual rule files for detailed explanations and code examples:

rules/auth-api-keys.md
rules/widget-integration.md
rules/item-lifecycle.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references
Pluggy-specific notes

Key Concepts

Connection Sync vs Data Sync

Responsibility	Who Handles	How
Connection sync	Pluggy	Auto-sync every 24/12/8h
Triggering updates	User	Only when user explicitly requests
Entity data sync	You	Fetch all on `item/updated` webhook
Transaction sync	You	Use `transactions/*` webhook events

API Key vs Connect Token

API Key: Backend token (2h expiration) for accessing user data
Connect Token: Frontend token (30min expiration) for Connect Widget only

Item Lifecycle

User opens Connect Widget with Connect Token
User selects connector and authenticates
Pluggy creates Item and starts data sync
Webhook notifies when sync completes
Backend retrieves data using API Key
Pluggy auto-syncs daily; webhook triggers data refresh

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

pluggy-integration