MFA Challenge Widget
When to expect them and how to test in sandbox.
MFA Challenge Widget
When to expect an MFA challenge, how to handle it.
Overview
Some banks ask the user for an extra check before they share account data. This check is a multi-factor authentication (MFA) challenge, for example a security question or a one-time code.
When a bank asks for MFA during a data job, Aerosync pauses the job and sets its status to pending_mfa. Your app then asks the user to verify, and relaunches the Aerosync widget so the user can answer. After the user answers, the job continues.
The bank decides, not your integration. You cannot predict which banks will ask for MFA, or when. Build every integration to handle it.
Two places MFA can appear
| When | What happens | What you build |
|---|---|---|
| During bank linking | The widget shows the challenge inside the linking flow | Nothing. The widget handles it |
| During a data job: identity, balance, or transactions | Aerosync pauses the job at pending_mfa | Detect the paused job, ask the user to verify, and relaunch the widget. This page covers this case |
Handle MFA on a data job
Step 1: Link a bank and store the connectionId
connectionIdThe user links a bank with the Aerosync widget. When onSuccess fires, store the connectionId. You need it for every data job and for the MFA relaunch.
Step 2: Create a data job and store the jobId
jobId| Data | Request | Guide |
|---|---|---|
| Identity | POST /v2/accounts/{connectionId}/identity | Account Holder Identity |
| Balance | POST /v2/accounts/{connectionId}/refresh | Balance Refresh |
| Transactions | POST /v2/accounts/{connectionId}/transactions | Transaction History |
Store the jobId from the response with the connectionId. The relaunch in Step 5 needs both.
The balance refresh response returns the job inside anaccountobject: readaccount.jobId. Identity and transactions returnjobIdat the top level.
Step 3: Detect that the job is waiting on MFA
Use one of these two methods:
- Webhook, recommended. Subscribe to
job.identity,job.balance, orjob.transaction. When the job needs MFA, the webhook payload hasstatus: "pending_mfa". See Handle Webhooks. - Polling, as a backup. Call
GET /v2/accounts/{connectionId}/job/{jobId}. When the job needs MFA, the response hasjobStatus: "Pending MFA"andmfaTriggered: true.
{
"status": "success",
"statusCode": 200,
"jobStatus": "Pending MFA",
"mfaTriggered": true,
"jobId": "IDT-ff1d12fc6dfa4b34ac9df85e676c30c0",
"connectionId": "8cf406e45b2442e2b1ef491a5ce4cd0d"
}Webhooks and polling spell the same states differently:
| Job state | Webhook status | Polling jobStatus |
|---|---|---|
| Started | initiated | "Initiated" |
| Waiting on MFA | pending_mfa | "Pending MFA" |
| Finished | completed | "Completed" |
| Failed or timed out | failed | "Failed" |
Compare status values without regard to case.
Step 4: Ask the user to verify
Tell the user that their bank needs a quick check, and give them one clear action. Keep the rest of your app usable while the job waits.

Example: a merchant app shows a banner on its home screen. The design is yours.
Step 5: Relaunch the widget with the MFA parameters
Launch the widget the same way as for bank linking, and add three parameters:
| Parameter | Value |
|---|---|
handleMFA | true |
jobId | The jobId from Step 2 |
connectionId | The connectionId from Step 1 |
The widget opens directly on the bank's challenge.
// Web SDK. For other platforms, see the widget integration guide for your SDK.
const widgetRef = initAeroSyncWidget({
elementId: "widget",
iframeTitle: "Verify with your bank",
environment: "sandbox",
token: widgetToken, // a widget token for this user, as for bank linking
aeroPassUserUuid: aeroPassUserUuid,
handleMFA: true, // required: open on the MFA challenge
jobId: jobId, // required: the job that is waiting on MFA
connectionId: connectionId, // required: the connection from the original link
onSuccess: function (event) {
// The user finished the challenge. The data is not ready yet:
// wait for the job to report completed or failed (Step 6).
},
onError: function (event) {
// The widget hit an error. Keep your prompt visible so the user can try again.
},
onClose: function () {
// The widget closed. If the job is still waiting on MFA, keep your prompt visible.
},
});
widgetRef.launch();
The relaunched widget opens directly on the bank's question.
Step 6: Wait for the job result
After the user answers, the job continues:
- Completed: the webhook sends
completed, or polling returns"Completed". Fetch the data with the GET request in the job's guide. - Failed: the webhook sends
failed, or polling returns"Failed". Start a new job if you still need the data.
Do not fetch data from onSuccess. Wait for the job status.
If the user does not answer
The challenge expires if the user does not answer in time. In sandbox, it expires after 5 minutes. TBD: the production timeout.
When the challenge expires, every job on that connection that is waiting on MFA moves to failed. To try again, start a new job. It pauses at pending_mfa again, and you repeat Steps 3 to 6.
Testing in the sandbox
For instructions to test in the sandbox environment, please refer to the guide here.
Updated 1 day ago