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

WhenWhat happensWhat you build
During bank linkingThe widget shows the challenge inside the linking flowNothing. The widget handles it
During a data job: identity, balance, or transactionsAerosync pauses the job at pending_mfaDetect 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

The 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

DataRequestGuide
IdentityPOST /v2/accounts/{connectionId}/identityAccount Holder Identity
BalancePOST /v2/accounts/{connectionId}/refreshBalance Refresh
TransactionsPOST /v2/accounts/{connectionId}/transactionsTransaction 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 an account object: read account.jobId. Identity and transactions return jobId at 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, or job.transaction. When the job needs MFA, the webhook payload has status: "pending_mfa". See Handle Webhooks.
  • Polling, as a backup. Call GET /v2/accounts/{connectionId}/job/{jobId}. When the job needs MFA, the response has jobStatus: "Pending MFA" and mfaTriggered: true.
{
  "status": "success",
  "statusCode": 200,
  "jobStatus": "Pending MFA",
  "mfaTriggered": true,
  "jobId": "IDT-ff1d12fc6dfa4b34ac9df85e676c30c0",
  "connectionId": "8cf406e45b2442e2b1ef491a5ce4cd0d"
}

Webhooks and polling spell the same states differently:

Job stateWebhook statusPolling jobStatus
Startedinitiated"Initiated"
Waiting on MFApending_mfa"Pending MFA"
Finishedcompleted"Completed"
Failed or timed outfailed"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:

ParameterValue
handleMFAtrue
jobIdThe jobId from Step 2
connectionIdThe 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.


Did this page help you?