Search...
APIJSLog inGet started in sandbox
Airwallex logo
Home
Platform APIs
Connected Accounts
Accounts
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Transfers
Create a transfer
Validate a transferManage transfers
Transfers to countries/regions with capital controls
Transfers via Airwallex PayEmbedded Transfer component

Embedded Transfer component

Note: To ensure full compatibility with the latest Transfer features and functionality, please verify that you are integrated with Client API version 2023-04-15 or later.

The Embedded Transfer component is a pre-built UI element for you to integrate into your own transfer flow for international bank transfers. It renders the user interface to help you collect required transfer information, such as country/region, beneficiary (recipient) type, transfer method, amount, date etc., while displaying other important information, such as currency conversion rates and fees.

Instead of building a native transfer flow from scratch, you can now use it along with the Embedded Beneficiary component to deliver a transfer experience that fully leverages Airwallex’s coverage while reducing development efforts and improving speed to market.

Please note that the Embedded Transfer component uses the same API version that you integrate with. As you upgrade API versions, the information rendered in the component will follow suit. This allows you to benefit from the continuous coverage expansion and product enhancements that Airwallex makes over time.

Key features include:

  • Dynamic transfer coverage, i.e., available currencies, countries/regions and transfer methods one can pay out to based on the token authentication
  • Customized theming to reflect your company's brand
  • A 1-minute stable currency conversion rate that can be shown to the user so they know exactly at what rate their funds will be converted
  • Ability to pre-fill information that have already been collected (e.g. amount), and disable or hide fields where applicable

To view and interact with the Embedded Transfer component, go to the Embedded Components demo site .

This page describes how to embed the transfer component on your page to start creating a transfer flow. See how to embed the beneficiary component in addition to the transfer component in Embedded Beneficiary component.

How it works

The diagram below depicts the interactions between the actor and the client-side system as well as the message exchanges between server-side systems during a transfer creation flow that involves the use of the Embedded Transfer component. This is a good place to start for understanding the high-level technical sequencing when using the component in your integration.

Embedded Transfer Component (1)

Before you begin

Step 1: Initialize the SDK

Import the SDK

JavaScript

Set up the server for authentication

Before beginning the process, you will need to get an authorization code to authorize the user into the Embedded Transfer component workflow. Always get authorization codes on the server side, a trusted environment. This prevents malicious users from being able to alter the scope.

When your page loads, on your server, call Authorize an account API with the following required fields in the request:

  • scope: Indicates the resources your application is allowed to access. For this SDK, you must provide w:awx_action:transfers_edit as the scope.
  • 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

Install js-base64 package.

JavaScript

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

Initialize the SDK with properties

In this step, we will verify your proof to use the SDK and prepare the component based on your configurations like running environment, display language, etc.

Call the asynchronous method sdk.init(options) with your credentials and configurations, and wait a little for us to get the component ready. For details of the options, please see Initialization JS.

JavaScript

Step 2: Add the Embedded Transfer component to your page

To embed a component into your page, you will need to create an empty container, create an instance of the component, and mount it to the container.

Define the container

First, create an empty container div with a unique id. Airwallex inserts an iframe into this div on mounting the instance of the component.

JavaScript

Create the Embedded Transfer component

To create the component, call createElement(type, options) and specify the type as payoutForm. This method creates an instance of the component. Components are rendered as iframes. For details of the properties, please see Create Element JS.

JavaScript

Mount the Transfer component

Call element.mount(domElement) to attach the instance of the component to the prebuilt container. The instance should only be mounted once.

JavaScript

Step 3: Interact with the Embedded Transfer component

You should have successfully embedded the Transfer component into your page. Now the user can interact with the component to provide information for making a transfer.

The transferComponent provides a set of methods and event listeners to handle user interactions.

For details of the transferComponent's events and methods, please see Interact with element object JS.

Events

Add event listeners to handle events received from Airwallex.

JavaScript

Events can be used to facilitate other flows in your user interface where applicable. Please find more details in the list of events below.

You can introduce different call-to-actions based on the user input by monitoring the values in the change event. For example, you can trigger an approval flow based on the source amount, i.e., when it is above a certain threshold amount, you can guide the user to go through a different user flow.

You can also monitor errors as part of the formState event and provide additional guidance for the users so they can fix the errors. The list of possible errors can be found in the Errors and events section.

Step 4: Retrieve the final payload from the Embedded Transfer component

When you are ready to retrieve the final payload to Create a new transfer API, you can call the submit function. It will trigger the validation of all fields in the component and return you the payload. For details of the final payload, please see Get final payload from submit method JS.

JavaScript

Next steps

Create a new transfer

You can create transfers with the payload you have retrieved by calling the Create a new transfer API endpoint. Please make sure that your request also contains the required beneficiary information.

  • If you have created beneficiaries with Airwallex previously, you can provide a beneficiary_id in your request.
  • If you already have the beneficiary information, you can specify the parameters in the beneficiary object in your request.
  • If you want to collect beneficiary information from your users similarly as you do for transfers, you can use the Embedded Beneficiary component to generate a beneficiary payload and aggregate it into your transfer payload.

See Create a transfer to learn more about this endpoint.

Please note that this API call should only happen on the server side, a trusted environment.

Test your integration

Build and test your integration in the sandbox environment first before going to production. Make sure to account for various success and error scenarios.

Troubleshooting

For troubleshooting tips, see Airwallex.js error codes.

Example integrations

We have a few examples of rendered components with different customizations. Check them out on the Embedded Components demo site .

FAQ

Does the transfer component support Strong Customer Authentication (SCA)?

The transfer component does not support Strong Customer Authentication (SCA). You still need to build SCA on top of the component (e.g. two-factor authentications) to comply with regulations such as the second Payment Services Directive (PSD2), if applicable.

Was this page helpful?
On this page
Was this page helpful?