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.
What carries over
Section titled “What carries over”| 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.
1. Turn on v2 for an API key
Section titled “1. Turn on v2 for an API key”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.
2. Upgrade the SDK
Section titled “2. Upgrade the SDK”npm install @banklink/sdk@0.4.0The 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, unchangedimport { BanklinkV2 } from '@banklink/sdk/v2'; // v2You 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.
3. Create and back up a customer key
Section titled “3. Create and back up a customer key”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 elseIf 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.
4. Relink each bank account
Section titled “4. Relink each bank account”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.
5. Move schedules into your application
Section titled “5. Move schedules into your application”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 |
| Send the digest from your application |
Pause the Pulse once the new job is running, so the account isn’t fetched twice.
6. Remove the v1 account
Section titled “6. Remove the v1 account”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.
Checklist
Section titled “Checklist”- An API key has v2 turned on
-
@banklink/sdkis 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.