@finsnap/connect-js

FinSnap Connect JavaScript SDK for securely linking Chilean financial accounts (SII, banks).

Installation

npm install @finsnap/connect-js

Or via CDN:

<script src="https://unpkg.com/@finsnap/connect-js/dist/finsnap-connect.js"></script>

Usage

1. Get a Link Token

First, create a link token from your backend:

POST /api/v1/link/token/create
Authorization: Bearer <your_access_token>

{
  "connection_type": "sii",
  "company_rut": "76.XXX.XXX-X"
}

2. Initialize the SDK

import { create } from '@finsnap/connect-js';

const handler = create({
  token: 'link_xxx', // from your backend
  onSuccess: (connectionId, metadata) => {
    console.log('Connected:', connectionId);
    // Save connectionId to your backend
  },
  onExit: (error, metadata) => {
    if (error) {
      console.error('Error:', error);
    }
    console.log('Status:', metadata.status);
  },
  onEvent: (eventName, metadata) => {
    console.log('Event:', eventName, metadata);
  },
  onLoad: () => {
    console.log('Widget loaded');
  },
});

3. Open the Widget

// Open the modal
handler.open();

// Later, to close programmatically
handler.exit();

// Clean up when done
handler.destroy();

API Reference

create(options)

Creates a new Connect handler.

| Option | Type | Required | Description | |--------|------|----------|-------------| | token | string | Yes | Link token from your backend | | onSuccess | (connectionId, metadata) => void | Yes | Called on successful connection | | onExit | (error, metadata) => void | No | Called when widget closes | | onEvent | (eventName, metadata) => void | No | Called for various events | | onLoad | () => void | No | Called when widget loads | | embedUrl | string | No | Custom widget URL (defaults to production) |

Handler Methods

| Method | Description | |--------|-------------| | open() | Opens the widget modal | | exit(options?) | Closes the widget | | destroy() | Cleans up resources |

Events

The onEvent callback receives these events:

| Event | Description | |-------|-------------| | LOAD | Widget loaded token info | | SUBMIT_CREDENTIALS | User submitted credentials | | SUCCESS | Connection successful | | ERROR | An error occurred | | CLOSE | Widget closed |

Environments

The SDK defaults to the production FinSnap Connect endpoint. For development and testing:

const handler = create({
  token: 'link_xxx',
  // Use dev environment for testing
  embedUrl: 'https://dev-api-services.finsnap.tax/link/embed',
  onSuccess: (connectionId, metadata) => {
    console.log('Connected:', connectionId);
  },
});

| Environment | URL | |-------------|-----| | Production | https://api-services.finsnap.tax/link/embed (default) | | Development | https://dev-api-services.finsnap.tax/link/embed |

Security

This SDK follows security best practices:

• No tokens in URLs: Link tokens are passed via postMessage, not URL query params
• Origin validation: Messages are only accepted from verified origins
• CSP headers: Widget is protected by Content-Security-Policy
• Single-use tokens: Link tokens expire after 30 minutes and can only be used once
• Sandboxed iframe: Widget runs in a sandboxed iframe with minimal permissions
• Strict message validation: Only messages from the expected origin with correct source/version are processed

Note: The embedUrl option should only be used to point to official FinSnap Connect endpoints (production or development). Never point to untrusted URLs.

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

License

MIT