Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Use cases
Hold & convert funds
Pay out funds
Create a payout
Using API and form schemasEmbedded Payout component

Embedded Payout component

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

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

Please note that the Embedded Payout 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 payout coverage, i.e., available currencies, countries/regions and payment 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 Payout component, go to the Embedded Components demo site .

This page describes how to embed the payout component on your page to start creating a payout flow. See how to embed the beneficiary component in addition to the payout 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 payout creation flow that involves the use of the Embedded Payout component. This is a good place to start for understanding the high-level technical sequencing when using the component in your integration.

Embedded Payout Component (1)

Before you begin

Step 1: Initialize the SDK

Import the SDK


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 Payout 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 a platform account API or Authorize a connected account API (as a platform account) 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.

Install js-base64 package.


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


Step 2: Add the Embedded Payout 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.


Create the Embedded Payout 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 .


Mount the Payout component

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


Step 3: Interact with the Embedded Payout component

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

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

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


Add event listeners to handle events received from Airwallex.


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

When you are ready to retrieve the final payload to Create a new payment 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 .


Next steps

Create a new payout

You can create payouts with the payload you have retrieved by calling the Create a new payment 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 payouts, you can use the Embedded Beneficiary component to generate a beneficiary payload and aggregate it into your payout payload.

See Create a payout 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 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.

Errors and events

This section lists all the errors and events you should monitor while initializing, creating and interacting with the Embedded Payout component.


Initialization errors

Error codes and descriptions for calling the sdk.init(options) method.

CodeDescriptionNext Step
FAILED_LOAD_SCRIPTUnexpected null document body.Make sure you added the SDK in client with the element in HTML.
FAILED_LOAD_SCRIPTFailed to load SDK script, please check your networkPlease check your network and try again.
INVALID_PARAMSInvalid {option_key}The SDK received an unsupported parameter while initializing. Please check the params table for valid options.
INVALID_PARAMSNo {parameter} providedMissing required parameter. Please check the params table for required options.
UNAUTHORIZEDclientId, authCode and codeVerifier do not match.Please check if the authentication was completed, the code verifier was generated successfully, and matching values are provided for the same authorization chain.
TOKEN_EXPIREDThe refreshToken have expired (valid for 1 hour).Please restart the entire flow by retrieving a new authCode and initializing the SDK, and then create the element again.
AUTH_TIMEOUTThe authorization has timed out after 30 seconds.Please restart the entire flow to get a new authCode, initialize the component, and create the component again.

Component creation errors

Error code and descriptions for calling the sdk.createElement(type, options) method.

CodeDescriptionNext Step
INVALID_ELEMENT_TYPEThe component type is not supported.Please check the supported element types and try 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.

Component mounting errors

Error code and descriptions for calling the mount() method.

CodeDescriptionNext step
MOUNT_CONTAINER_NOT_EXISTThe mount container does not existPlease check if the container dom id or the dom element passed in the mount() function is valid.

Payout form

onError events

Events indicating errors to listen for after the component is mounted.

CodeDescriptionNext Step
INVALID_BENEFICIARY_IDThe beneficiary_id you provided in the defaultValue is invalid.Provide a valid beneficiary ID that belongs to this account, or specify parameters for the beneficiary instead.
SCHEMA_NOT_FOUNDThe defaultValue provided is not supported in our schema.Provide a supported combination of values for sourceCurrency, paymentCurrency, bankCountryCode, paymentMethod, and localClearingSystem.

formState events

Events to listen for as the user interacts with the component with suggestions to handle on your user interface.

CodeDescriptionNext Step
SCHEMA_NOT_FOUNDThe values provided are not supported in our schema.Provide a supported combination of values for sourceCurrency, paymentCurrency, bankCountryCode, paymentMethod, and localClearingSystem.
AMOUNT_ABOVE_LIMITThe amount exceeds the transfer limit.Provide a lower amount.
AMOUNT_ABOVE_PAYMENT_LIMITThe amount exceeds the transfer limit.Provide a lower amount.
AMOUNT_BELOW_LIMITThis amount is lower than the minimum transfer limit.Provide a higher amount.
AFTER_FEE_IS_TOO_SMALLThis amount is lower than the minimum transfer limit after deducting payout fee.Provide a higher amount.
INVALID_AMOUNT_MAX_THREE_DECIMALSThis amount only supports three decimal places maximum.Provide a valid amount with no more than three decimal places.
INVALID_AMOUNT_MAX_TWO_DECIMALSThis amount only supports two decimal places maximum.Provide a valid amount with no more than two decimal places.
INVALID_AMOUNT_NO_DECIMALSThis amount does not support any decimal places.Provide a valid amount without any decimal places.
INVALID_AMOUNT_MUST_POSITIVEThis amount can only be positive.Provide a positive amount.
INVALID_SETTLEMENT_DATEThe payout date is not supported.Provide a valid payout date.
INVALID_CURRENCY_PAIRThe sourceCurrency and paymentCurrency combination specified is not supported or enabled for this account.Provide a supported sourceCurrency and paymentCurrency pair.
UNSUPPORTED_CURRENCYThe currency specified is not supported or enabled for this account.Provide a valid sourceCurrency or paymentCurrency.
MISSING_FEE_CONFIGThere is a problem with this account’s payout fee configuration.Contact your Account Manager and report this issue.

Example integrations

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


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

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

On this page