​
Prerequisites

Before you begin, make sure you have:
  • A developer account with us
  • API Key and Webhook Signing Secret
  • Basic understanding of RESTful APIs

​
Step-by-Step Guide

You can either use our SDK or make direct API requests. Check out the API Reference for more information on using the API directly.
1

Install the SDK

We currently support Node.js and Python. Ask us if you need support for other languages.
npm install @getivy/node-sdk
2

Initialize the Client

import Ivy from '@getivy/node-sdk';

const client = new Ivy({
  apiKey: 'YOUR_IVY_API_KEY',
  environment: 'sandbox', // defaults to 'production'
})
3

Create Data Session

Create a new data session. The response will contain a redirectUrl that you can use to redirect the customer to their bank’s authentication flow and a session id called id which you need later to fetch accounts, balances and transactions. After successful authentication, the customer will be redirected to the successCallbackUrl.
TypeScript
const dataSession = await client.data.session.create({
  referenceId: 'your-unique-id',
  metadata: {
    'merchant-id': '1234567890',
    'random-key': 'random-value',
  },
  locale: 'en',
  market: 'de',
  successCallbackUrl: 'https://your-app.com/callback',
  errorCallbackUrl: 'https://your-app.com/callback'
})

// Redirect the customer to the redirectUrl in the Client
res.send(dataSession.redirectUrl)
4

Pull Account Data

After the user finished the authentication flow and returned to the redirectUrl, you can start making API requests:
TypeScript

// Retrieve the data session to check the status (once completed, you can check consent status)
const dataSession = await client.data.session.retrieve({
  id:  dataSession.id,
})

// Check consent status (if authorised you can pull data)
const consent = await client.data.consent.retrieve({
  sessionId: dataSession.id,
})

// Retrieve the customer's account
const account = await client.data.accounts.list({
  sessionId: dataSession.id,
})

// Get account transactions
const transactions = await client.data.transactions.list({
  sessionId: dataSession.id,
})

// Get account balances
const balances = await client.data.balances.list({
  sessionId: dataSession.id,
})

// Revoke consent once not needing to pull data anymore
await client.data.consent.revoke({
  sessionId: dataSession.id,
})

​
Authentication

Our API uses API Key authentication for secure access. Make sure to securely store your credentials and never expose them in client-side code.

​
Available Account Data

You can request the following data from your customer’s bank:
PermissionDescription
accountsAccess account data
balancesAccess balance data
transactionsAccess transaction data

​
Testing

We provide a sandbox environment for testing your integration: 
BASE_URL=https://api.sand.getivy.de

​
Next Steps