Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewHow Airwallex Payouts work
Payout network
Use cases
Create beneficiariesValidate a beneficiaryRetrieve beneficiariesManage beneficiariesUsing API and form schemas Embedded Beneficiary component
Test and go live
Older API versions

Embedded Beneficiary component

The Embedded Beneficiary component is a pre-built UI element for you to integrate into your own flow for beneficiary (recipient) information collection. It renders the user interface to help you collect required beneficiary information, such as bank account details, business/personal information.

Instead of building a native beneficiary creation flow from scratch, you can now use it to deliver an experience that fully leverages Airwallex’s coverage while reducing development efforts and improving speed to market.

Please note that the Embedded Beneficiary 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 and the corresponding sets of required beneficiary information based on the token authentication
  • Customized theming to reflect your company's brand
  • Ability to pre-fill information that have already been collected (e.g. address), and disable or hide fields where applicable

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

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

Embedded Beneficiary 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 Beneficiary component workflow. Always get authorization code 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 Beneficiary 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 Beneficiary component

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


Mount the Beneficiary 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 Beneficiary component

You should have successfully embedded the Beneficiary component into your page. Now the user can interact with the component to provide information for creating a beneficiary.

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

For details of the beneficiaryComponent'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.

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.


Below lists the methods that the beneficiaryComponent has.

mountUse this function to mount the component. This could be a DOM element or an HTML element id.
unmountUse this function to unmount the component from the DOM tree.
destroyUse this function to destroy the component. A destroyed component cannot be re-mounted to the DOM.
onListen for component events.
submitRetrieve the final payload on submit.

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

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

Once the beneficiary payload is retrieved, you can create a new beneficiary API in Airwallex. You can also use the beneficiary payload to update a beneficiary API that you have already saved with Airwallex.

Create a new payout

With the beneficiary created, you can call the Create a new payment API endpoint with the beneficairy_id to create a payout. You can also create a new payout without creating a beneficiaries by directly using the beneficiary payload retrieved from the beneficiary form in your request. See Create a payout to learn more about this endpoint.

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

Render payout experience for a beneficiary

If you also want to render an experience where you allow the user to specify amount, date etc. and view currency conversion rates and fees, you can consider using the Embedded payout components.

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


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.

Beneficiary form

onError events

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

CodeDescriptionNext Step
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.
VALIDATION_FAILEDThe request failed our schema validation.Check the errors on the form and update with accepted values.

Example integrations

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


Can I save the beneficiary information on my own database?

Yes, you can choose to save beneficiary information on your side without creating beneficiaries with Airwallex. In this case you can use our Embedded Beneficiary component to generate beneficiary payloads, save them on your server in the manner you prefer, and directly use them to create payouts along with payout information when needed.

On this page