Embedded Beneficiary component

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

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.

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 .

First, create an empty container div with a unique id. Airwallex inserts an iframe into this div on mounting the instance of the 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 .

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

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.

You can choose to save beneficiary information in Airwallex's system or on your side (your own database) 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.

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. To do this, you must:

1. Retrieve current details of the beneficiary by calling either Get list of beneficiaries API or Get a beneficiary by ID API.
2. Pre-fill the retrieved beneficiary details as default values in the Embedded Beneficiary component. This allows users to see the current information and make necessary updates.
3. After the user updates the information using the Embedded Beneficiary component, call the submit() method to retrieve the updated details.
4. Send the updated beneficiary information back to your server and call Update a beneficiary API to update the beneficiary in Airwallex's system.

With the beneficiary created, you can call the Create a new transfer API endpoint with the beneficiary_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 transfer to learn more about this endpoint.

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

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.

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.