Embedded SCA component

The Embedded SCA component is a pre-built UI element designed to handle the SCA flow with enhanced security for transactions initiated by the platform on behalf of connected accounts. By integrating this component, users benefit from robust multi-factor authentication that protects sensitive transactions and data access. This ensures regulatory compliance and reduces fraud risk. With our SCA component, platform users can create a secure and reliable environment, increasing confidence and ensuring safer digital interactions.

Instead of building your own native SCA flow, you can now deliver a compliant SCA experience that leverages the following features:

Allows end users to configure two-factor authentication as a preliminary setup process.
Offers enhanced security via two-factor authentication during payment transactions.
Utilizes SCA exemptions to minimize friction in the payment experience.
Implements customized theming to align with your company's branding.

To view the SCA experience offered by the Embedded SCA component, go to the Airwallex demo site .

This page describes how to embed the SCA component into your page to start authenticating customers for sensitive transactions and data access.

Before you begin

Contact your Airwallex Account Manager to enable SCA flow using Embedded Components.
Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Explore the SCA Element reference JS to familiarize yourself with the SCA Element methods, parameters, and properties.
Install and initialize Airwallex.js JS.
Build and test your integration in a demo environment first before going to production. Make sure to account for various success and error scenarios. Contact your Account Manager to get Airwallex demo accounts set up.

Step 1: Initialize the SDK

First, you will need to import the components-sdk and then initialize the environment. For details, see Initialization JS.

Set up the server for authentication

When the user, i.e., the connected account holder, begins the SCA process, you will need to get an authorization code to authorize them into the Embedded SCA workflow. Always get authorization code on the server side, a trusted environment. This prevents malicious users from being able to alter the scope.

When the SCA page loads, on your server, call Authorize a connected account API by providing the required fields in the request.

Shell

scope: Indicates the resources your application is allowed to access. For Embedded SCA onboarding, you must provide w:awx_action:sca_edit and r:awx_action:sca_view as the scope.
identity: The platform’s identifier for the user handling the SCA flow, such as a user ID from the system. The SCA information will be linked to this identifier.
code_challenge: Generate a challenge token together with the code_verifier using the S256 generation method as described in RFC 7636 Section 4. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))). Use a third-party package to generate code_verifier and code_challenge or use the following code example in Javascript.

JavaScript

The authorization_code is returned in the response, which you should then return to the client side as authCode in order to initialize the SDK.

Step 2: Add the Embedded SCA component to your page

To embed the SCA flow into your page, you will need to create an empty container, create the SCA component and then mount the element to the container.

Define the SCA onboarding container

First, create an empty container div with a unique id in your page. Airwallex inserts an iframe into this div on mounting the element.

Add the Embedded SCA component

To add the SCA component, call createElement(type, options) and specify the required parameters. This method creates an instance of an individual component. Components are rendered as iframes.

SCA setup flow

The SCA setup element guides users through the initial SCA setup, allowing them to configure two-factor authentication (e.g., passcode and SMS) for secure account access. It's recommended to launch setup immediately after connected account onboarding to reduce potential risks. Note: Users who have not set up SCA will first be redirected to the setup flow within the SCA Management and SCA Verify flows.

For the SCA setup flow used for pre-configuration, specify type as scaSetup or scaManagement in createElement(type, options) method.

JavaScript

SCA management flow

The SCA management element is designed to simplify management of SCA settings. Currently platforms can embed this component in a dedicated management page to verify if SCA has been enabled for the user. This component must be used in conjunction with other SCA Elements (SCA Setup, SCA Verify).

To manage SCA settings using the SCA management flow, specify type as scaManagement in createElement(type, options) method.

JavaScript

SCA verify flow

The SCA verify element verifies user identity for sensitive operations such as initiating transactions or accessing critical account information. It prompts users to enter authentication factors (e.g., passcode, 2FA code) to confirm their identity and authorize operations. This component must be used in conjunction with other SCA Elements (SCA Setup, SCA Management).

For the SCA verify flow used for verification on demand, specify type as scaVerify in createElement(type, options) method.

JavaScript

You can also pass options in createElement() to overwrite styles and other functions. For details, see SCA Element props JS.

Mount the element

Call element.mount() with the id of the div container to mount the element to the DOM. This builds an embedded SCA workflow. The element should only be mounted once in a single SCA flow.

JavaScript

For all the other methods supported on this component, see Element object methods .

Handle the ready event

Add the ‘ready’ event JS listener to ensure the SCA component is rendered. It's recommended that you show a loading state UI before receiving the ‘ready’ event.

JavaScript

Step 3: Handle the response

Add success and error event listeners to handle error and success events received from Airwallex.

JavaScript

If the verification is successful, display a message that SCA enablement was successful. You can resubmit your API requests using the SCA token, for example, funds transfers or transaction data retrieval.
If SCA fails with an error, display the appropriate message to your end user so they can take action and try again. See Element events JS.

See table below for the common error codes and recommended next steps.

Error code	Error message	Next steps
INIT_ERROR	No `<parameter>` provided	Check the required `init()` JS options.
INIT_ERROR	Failed to authorize	Confirm that the `clientId`, `env`, `codeVerifier` and `authCode` passed in the `init()` JS function are valid.
INIT_ERROR	Auth timeout	Please check if your network connection is stable. If so, please contact Airwallex support.
UNAUTHORIZED	Failed to refresh token	The `refreshToken` might be expired (currently 1 hour). Please redo the entire flow to get a new `authCode` and initialize the SDK, and then create the element again.
CREATE_ELEMENT_ERROR	Please `init()` before `createElement()`	Please confirm you have correctly loaded the SDK script using the `init()` function.
CREATE_ELEMENT_ERROR	`CreateElement` with type `<type>` not supported	Check the supported types JS.
MOUNT_ELEMENT_ERROR	Cannot find element with dom element id: `<id>`	Please check if the container dom id or the dom element passed in the `mount()` function is valid.
SUBMIT_FAILED	Internal API error: Failed to submit form.	Please retry or contact Airwallex support.
UNKNOWN	Unknown error	Please retry or contact Airwallex support.
API_ERROR	`<API_name>` API error	Error occurred when calling internal API. Please retry or contact Airwallex support.
- (Console message only)	Please initialize Airwallex SDK	Please confirm if you have correctly loaded the SDK script using the `init()` function.

Test your integration

You may test your integration for various success and error scenarios in the demo environment and then go live in the production environment. Contact your Airwallex Account Manager for test account details.

To trigger SDK errors during testing, use these instructions.

Error Code	How to trigger
INIT_ERROR	Call `init()` function with unsupported values for options, e.g., `await init({env: 'other'})` where `other` is not supported
UNAUTHORIZED	Internal error, unable to trigger
AUTH_TIMEOUT	Block your network
CREATE_ELEMENT_ERROR	Call `createElement()` function with unsupported element type, e.g., `createElement('wrong_type')`
MOUNT_ELEMENT_ERROR	Call `mount()` method with a non-existent div id. e.g., `element.mount('nonexistent-div-id')`
SUBMIT_FAILED	Internal error, unable to trigger
UNKNOWN	Internal error, unable to trigger
API_ERROR	Block your network

FAQ

How do I customize the embedded component?

Contact your Airwallex Account Manager to enable customization of the look and feel in line with your brand. Your Account Manager will assist you in generating a theme schema, which can be passed into the component upon initialization.

The theme schema includes:

Colors: You can recolor the component by specifying a set of 10 colors which makes up a color gradient. The colors can be in one or multiple tones.
Component-level configuration
Typography

JavaScript

What are the recommended dimensions for the component?

The component is responsive and designed for a variety of common screen resolutions.

However, the suggested web dimensions for responsiveness are:

Width: 500px
Height:
- 2000px to avoid a scroll bar
- 750px with a scroll bar

Embedded SCA component

.css-1xcsryl>.e1x8zjqq1{opacity:0;-webkit-transition:opacity 250ms ease-in-out;transition:opacity 250ms ease-in-out;}.css-1xcsryl:hover>.e1x8zjqq1{opacity:1;}Before you begin.css-158icaa{margin-left:4px;}

Before you begin