Skip to content

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

Banklink Docs

Progress, approvals and PINs

Show the account holder what a v2 job is doing, handle approvals in the banking app and one-time PINs, and cancel jobs.

A job can take a while. The bank may want the sign-in approved in its app, or a one-time PIN. Every job method (syncOnce, create, sync, verify) takes the same options for this.

onStatus is called when the job moves to a new stage:

stage Meaning
preparing Checking the worker and building the release
signing_in The worker is signing in to the bank
awaiting_approval Approve the sign-in in the bank’s app before expiresAt
awaiting_otp The bank asked for a one-time PIN
awaiting_qr_scan Show image for the account holder to scan in the bank’s app before expiresAt (Capitec, SDK 0.4.0)
qr_expired The code lapsed. Call requestRetry() before retryUntil if the account holder wants a new one
fetching Signed in, reading accounts and transactions
decrypting The result arrived and is being decrypted on your side

Some stages are skipped. Errors thrown inside onStatus are ignored, so a broken progress display can’t fail the job.

await banklink.profiles.sync(id, {
onStatus(status) {
if (status.stage === 'awaiting_approval') showApprovalCountdown(status.expiresAt);
else showStage(status.stage);
},
});

When the bank wants the sign-in approved in its app, you get awaiting_approval with an expiresAt deadline you can show as a countdown. If the bank sends a fresh notification, the event comes again with a new deadline and resent: true. If nobody approves in time, the job fails with ApprovalNotGivenError.

Capitec shows a QR code at every sign-in. You get awaiting_qr_scan with image (a data: URL you can put straight into an <img>), an expiresAt deadline and attempt. If the code lapses, you get qr_expired with retryUntil and a requestRetry() action. Call it only when the account holder asks for a new code. v2 allows two codes per job; after that, or if nobody scans, the job fails with ApprovalNotGivenError.

onStatus(status) {
if (status.stage === 'awaiting_qr_scan') showQr(status.image, status.expiresAt);
if (status.stage === 'qr_expired') offerNewCode(status.retryUntil, () => status.requestRetry());
},

If the bank asks for a one-time PIN, the SDK calls onOtp and sends what it returns. Without onOtp, the job is cancelled with OtpRequiredError. After 3 PINs in one job it stops with otp_limit.

onOtp: async () => askTheAccountHolderForTheirPin(),

Pass an AbortSignal as signal to cancel a job, or timeoutMs to limit how long it can run. A cancelled job throws a CeremonyError with code cancelled, and a timed-out one with timeout. The SDK tells Banklink to drop the job either way.