Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Embedded Finance
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Business Account Help Center
API Reference
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Use cases
Airwallex gateway
PSP agnostic
Hold & convert funds
Pay out funds
Connected accounts
Compliance Support
Compliance requirementsStrong Customer Authentication (SCA)
SCA for funds transfersSCA for transaction data retrievalEmbedded SCA component
SCA exemptions
Mentions of Airwallex in Platform's user interfaces
Risk
Platform operations

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 by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
  • Explore the @airwallex/components-sdk JavaScript client library reference to familiarize yourself with the Embedded SCA component methods, parameters, and properties.
  • Install the package
    • Using Yarn or NPM
      • yarn add @airwallex/components-sdk
      • npm install @airwallex/components-sdk
    • Using CDN
      • <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>

Step 1: Initialize the components web SDK

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

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
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

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

JavaScript

SCA verify flow

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 component props .

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 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 .

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

Error codeError messageNext steps
INIT_ERRORNo <parameter> providedCheck the params table for required init options.
INIT_ERRORFailed to authorizeConfirm that the clientId, env, codeVerifier and authCode passed in the init() function are valid.
INIT_ERRORAuth timeoutPlease check if your network connection is stable. If so, please contact Airwallex support.
UNAUTHORIZEDFailed to refresh tokenThe 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_ERRORPlease init() before createElement()Please confirm you have correctly loaded the SDK script using the init() function from our package or the CDN link.
CREATE_ELEMENT_ERRORCreateElement with type <type> not supportedCheck the supported types .
MOUNT_ELEMENT_ERRORCannot 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.
PERMISSION_DENIEDUser does not have access permission.Account is not eligible to access Airwallex Online Payments. Please check that the account has applied for general onboarding (KYC). For further inquiries, please contact Airwallex support.
SUBMIT_FAILEDInternal API error: Failed to submit form.Please retry or contact Airwallex support.
UNKNOWNUnknown errorPlease retry or contact Airwallex support.
API_ERROR<API_name> API errorError occurred when calling internal API. Please retry or contact Airwallex support.
- (Console message only)Please initialize Airwallex platform onboarding SDKPlease confirm if you have correctly loaded the SDK script using the init() function from our package or the CDN link.

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 CodeHow to trigger
INIT_ERRORCall init() function with unsupported values for options, e.g., await init({env: 'other'}) where other is not supported
UNAUTHORIZEDInternal error, unable to trigger
AUTH_TIMEOUTBlock your network
CREATE_ELEMENT_ERRORCall createElement() function with unsupported element type, e.g., createElement('wrong_type')
MOUNT_ELEMENT_ERRORCall mount() method with a non-existent div id. e.g., element.mount('nonexistent-div-id')
SUBMIT_FAILEDInternal error, unable to trigger
UNKNOWNInternal error, unable to trigger
API_ERRORBlock 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
On this page