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.
Progress events
Section titled “Progress events”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); },});Approval in the banking app
Section titled “Approval in the banking app”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.
QR codes (Capitec)
Section titled “QR codes (Capitec)”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());},One-time PINs
Section titled “One-time PINs”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(),Cancel or time out
Section titled “Cancel or time out”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.