Skip to content

Banklink v2Customer-held keys and one-off fetches, through the Node.js SDK. v1 is unchanged.Migration guide

Banklink Docs

Migrating from v1

Move an existing Banklink integration to v2 step by step. Your sign-in, organisation and API keys stay the same. Bank accounts need relinking.

You don’t have to migrate. v1 keeps working: the API, Pulses, webhooks, email digests, the hosted link page and the dashboard. If we ever plan to change that, we’ll announce it in the changelog first and give you notice.

Move to v2 when you want customer-held keys: saved bank logins that only your application can approve, and results decrypted in your own code.

Carries over?
Banklink sign-in, organisation and team Yes. Nothing to recreate
API keys Yes. Turn on v2 for the key you want to use (step 1)
Credits and billing Yes
Linked bank accounts No. Relink each account through v2 (step 4)
Pulses, webhooks and email digests No. Schedule fetches in your application (step 5)
Stored transactions Stay in the dashboard for your v1 accounts. v2 doesn’t store transactions

A v1 bank login is encrypted with a Banklink key. v2 needs it encrypted in your application, under your customer key. Banklink can’t convert one into the other, so every account you move is linked again.

In the dashboard, open Settings → API Keys (more in API keys):

  • For an existing live key, choose Turn on v2.
  • For a new key, keep Allow v2 ticked when you create it.

The key keeps every v1 permission it had, so your current integration doesn’t notice. Only live keys can use v2. You need editor access or above.

Terminal window
npm install @banklink/sdk@0.4.0

The default Banklink export still talks to v1, so upgrading changes nothing on its own. v2 is a separate client:

import { Banklink } from '@banklink/sdk'; // v1, unchanged
import { BanklinkV2 } from '@banklink/sdk/v2'; // v2

You can run both side by side while you move accounts across. v2 is in the Node.js SDK today. v2 support in the Python SDK is coming soon; until then, Python integrations stay on v1.

Skip this step if you only do one-off fetches with profiles.syncOnce. They use a throwaway key.

For saved connections, register a customer key once. keys.init() generates a seed, registers its public half and returns the seed:

const banklink = new BanklinkV2({ apiKey: process.env.BANKLINK_API_KEY! });
const seed = await banklink.keys.init();
await saveToYourSecretManager(seed); // do this before anything else

If you’d rather generate the seed yourself and back it up first, pass it in: keys.init(seed). Either way, the seed must reach your secret manager. Banklink only holds the public half and can’t recover a lost seed. If you lose it, you’ll have to relink every account that used it.

For each account you move, collect the bank login in your own interface and create a v2 profile:

const profile = await banklink.profiles.create({
bank: 'fnb',
fields: { username, password },
onOtp: async () => collectOtpPrivately(),
});
// profile.data holds the first fetch. Later fetches: banklink.profiles.sync(profile.id)

Store profile.id next to the v1 account ID in your own database, so you know which accounts have moved. If the account holder approves sign-ins in a banking app or with a one-time PIN, they’ll need to do that during the relink. Show them progress with onStatus.

FNB and Standard Bank work with SDK 0.3.0, and Capitec from 0.4.0. Leave Nedbank and other banks on v1 for now. See Banks.

v2 has no Pulses. Replace each Pulse with a job in your own scheduler (cron, a queue or a task runner) that calls profiles.sync. Then handle the result where the Pulse used to deliver it:

Pulse destination In v2
Dashboard Save the result in your own database
Webhook Call your handler directly with the result
Email Send the digest from your application

Pause the Pulse once the new job is running, so the account isn’t fetched twice.

When the v2 profile syncs on schedule, remove the v1 account. Use Remove account on the dashboard’s Accounts page, or call DELETE /v1/accounts/{id}/credentials with a key that has credentials:delete. This deletes the saved v1 login, the account’s stored transactions and its sync history, and switches off its Pulses. It can’t be undone, so save any transactions you still need first.

Until you remove it, the v1 account still works. To roll back, switch your code back to the v1 client and resume the Pulse.

  • An API key has v2 turned on
  • @banklink/sdk is 0.3.0 or later
  • The customer key is backed up in your secret manager and registered (saved connections only)
  • Each account is relinked, with its v2 profile ID saved
  • Each Pulse is replaced by a job in your application and paused
  • Each moved v1 account is removed, after you’ve kept any transactions you need

Stuck? Email support@banklink.co.za. Never send an API key, customer key or bank login to support.