Banklink v2 is open to every Banklink organisation. It's a second way to fetch bank data, built around one change: your application holds the key that unlocks a saved bank login. Your code approves each fetch and decrypts the result. Banklink relays it.

You use v2 through the Node.js SDK, with the Banklink sign-in, organisation and API keys you already have. v2 support in the Python SDK is coming soon. Nothing about v1 changes. The API, Pulses, webhooks, the hosted link page and the dashboard all keep working.

Your key unlocks the login, one job at a time

For a saved connection, the SDK encrypts the bank login in your application before it reaches Banklink. Your customer key stays in your systems, and Banklink only holds its public half. Before each fetch, the SDK checks the signed details of the job and the worker, then approves a sealed release for that job alone.

The bank-connection worker opens the login for that job and signs in to the bank. It encrypts the result to your application's key, and the SDK decrypts it on your side. The API in between only sees sealed payloads. Banklink keeps metadata and usage counts, not a copy of your transactions.

The worker is run by Banklink and has to read the login and the bank data while a job runs. Customer-held keys don't hide that from its operator. What they do is decide when a saved login can be unlocked, and protect everything that passes through the API. The security overview covers the wider picture.

One-off fetches need no saved key

If you need data once, profiles.syncOnce creates a throwaway key for that job and wipes it afterwards. You collect the bank login in your own interface. The SDK seals it, collects the result and decrypts it. There's nothing to register first.

npm install @banklink/sdk@0.4.0
import { BanklinkV2 } from '@banklink/sdk/v2';

const banklink = new BanklinkV2({
  apiKey: process.env.BANKLINK_API_KEY!,
});

const result = await banklink.profiles.syncOnce({
  bank: 'fnb',
  fields: await collectBankLoginPrivately(),
  onOtp: async () => collectOtpPrivately(),
  onStatus(status) {
    updateProgress(status);
  },
});

The input and progress functions are your own code. Keep logins, one-time PINs, customer keys and results out of your logs, and check the shape of the result before you use it.

Show people what the bank is waiting for

onStatus reports each stage of a job: preparing, signing in, waiting for approval in the banking app, waiting for a one-time PIN, fetching and decrypting. Some stages are skipped.

When the bank wants the sign-in approved in its app, the event carries a deadline you can show as a countdown. If the bank sends a fresh notification, you get the new deadline. The person approving knows what to do next while your application waits.

Getting started from the dashboard

There's no new portal to sign in to. In the dashboard, open Settings → API Keys. New live keys have Allow v2 ticked. Existing live keys have a Turn on v2 button. Either way the key keeps all of its v1 permissions, so your current integration carries on as before.

v2 works with FNB and Standard Bank today, with live keys. Test keys are refused, and there's no hosted v2 sandbox yet. v2 support in the Python SDK is coming soon. Until then, the Python SDK covers v1.

Moving an existing integration

You don't have to move. If you want customer-held keys, the migration guide walks through it. In short:

  1. Turn on v2 for an API key.
  2. Upgrade to @banklink/sdk 0.3.0. The default export still talks to v1, so the upgrade alone changes nothing.
  3. For saved connections, create a customer key and back it up in your secret manager.
  4. Relink each bank account through v2. A v1 login is encrypted with a Banklink key, so it can't be turned into a v2 login. Every account you move is linked again.
  5. Replace each Pulse with a job in your own scheduler, then pause the Pulse.
  6. Remove the v1 account once the v2 one runs on schedule.

Back up your customer key before you register it. Banklink can't recover a lost key. If it's lost, you'll have to relink the accounts that used it.

The v2 guide covers limits, errors and key rotation. The SDK repository has the full reference and the customer-side cryptographic source. For background on connecting to local banks, see our South African bank API guide.