Embedded Tax Form component

The Embedded Tax Form component is a pre-built UI element for you to integrate into your own flow for recipient tax information collection. It renders the user interface to help you collect required tax information, such as TIN/SSN details, name, address information.

Key features include:

Dynamic tax information collection including forms W-9, W-8BEN, W-8BEN-E, W-8ECI, W-8EXP and W-8IMY
Automatic TIN matching for W-9
W-9/W-8 form retrieval and download
e-Delivery of 1099-NEC form

To view and interact with the Embedded Tax Form component, go to the demo site .

Before you begin

Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Explore the Tax Form Element reference JS to familiarize yourself with the Tax Form Element methods, parameters, and properties.
Install and initialize Airwallex.js JS. If your integration currently uses Airwallex Payouts Web SDK , refer to our upgrade guide for information on migrating to Airwallex.js.
Build and test your integration in the sandbox environment first before going to production. Make sure to account for various success and error scenarios.

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 tax form component workflow. Always get authorization code on the server side, a trusted environment. This prevents malicious users from being able to alter the scope. For more details, please see Embedded Components API.

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 embedded tax form components, you must provide the following scopes: r:awx_action:tax_form_view and w:awx_action:tax_form_edit
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.

Note: The Identity field is mandatory for the tax form component. This field serves as the external identifier used to locate users on your platform. This should be the same as the external_identifier when calling our transfer API.

JavaScript

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

JavaScript

Step 2: Add the Embedded Tax Form 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 Tax Form component

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

You can use the theme builder button at the bottom right corner of the demo site to get the theming options.

JavaScript

Step 3: Interact with the Embedded Tax Form component

You should have successfully embedded the tax form component into your page. Now the recipient can interact with the component to provide tax information.

JavaScript

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.

Tax Identification Number (TIN) Validation

Use the below test TINs in the demo environment to trigger different statuses.

TIN Value	Final status
123456783	Ready
123456784	Ready
123456785	Pending verification
123456786	Ready
123456787	Pending verification
123456788	Pending verification
123456789	Failed verification
Other	Ready

Troubleshooting

For troubleshooting tips, see Airwallex.js error codes.

Was this page helpful?