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
1
2yarn add '@airwallex/components-sdk'
3
4//Or with npm
5npm install '@airwallex/components-sdk'
6

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
1// Generate code_verifier
2const dec2hex = (dec: number) => {
3  return ('0' + dec.toString(16)).slice(-2);
4};
5
6const generateCodeVerifier = () => {
7  // generate random length for code_verifier which should be between 43 and 128
8  const length = Math.random() * (129-43) + 43;   
9  const array = new Uint32Array(length/2);
10  window.crypto.getRandomValues(array);
11
12  return Array.from(array, dec2hex).join('');
13};
14
15const codeVerifier = generateCodeVerifier();

Install js-base64 package.

JavaScript
1import { Base64 } from 'js-base64';
2
3// Generate code_challenge
4const sha256 = (plain: string) => {
5  const encoder = new TextEncoder();
6  const data = encoder.encode(plain);
7  return window.crypto.subtle.digest('SHA-256', data);
8};
9
10const base64urlencode = (hashed: ArrayBuffer) => {
11  const bytes = new Uint8Array(hashed);
12  const base64encoded = Base64.fromUint8Array(bytes, true);
13  return base64encoded;
14};
15
16export const generateCodeChallengeFromVerifier = async (codeVerifier: string) => {
17  const hashed = await sha256(codeVerifier);
18  const base64encoded = base64urlencode(hashed);
19  return base64encoded;
20};
21
22const codeVerifier = await generateCodeChallengeFromVerifier(codeVerifier);

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.

JavaScript
1// server side
2import axios from 'axios';
3const requestBody = {
4  "code_challenge": "aNggeDw6KT4422DzzGe1RUZC2DJ-cpLi3hM8b7YRFeE",
5  "identity": "089cc0ec-0a6f-4150-90351232", // Taxpayer external id
6  "scope": [
7     'r:awx_action:tax_form_view',
8     'w:awx_action:tax_form_edit',
9  ]
10};
11
12axios
13  .request({
14    url: 'https://api-demo.airwallex.com/api/v1/authentication/authorize',
15    method: 'post',
16    headers: {
17      'Content-Type': 'application/json',
18      'Authorization': 'Bearer xxxxx' // Authorization token payload
19   },
20    data: requestBody,
21  })
22  .then(({ data }) => { ... })
23  .catch(error => { ... });

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
1import { init } from '@airwallex/components-sdk';
2const options = {
3  locale: 'en',
4  env: 'prod',
5  enabledElements: ['payouts'],
6  authCode: 'x4D7A7wOSQvoygpwqweZpG0GFHTcQfVPBTZoKV7EibgH',
7  clientId: 'BIjjMYsYTPuRqnkEloSvvf',
8  codeVerifier:'~wh344Lea1FsCMVH39Fn9R2~n',
9};
10await init(options);

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
1<!--Create an empty container for the instance of the component→
2<div id="tax-form-container"></div>

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
1const taxFormElement = await createElement('taxForm', { theme: THEME_OPTIONS}); 
2
3// mount the element on your page with container DOM id
4taxFormElement.mount('<container_dom_id>');

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
1taxFormElement.on('ready', () => {
2 // remove loading state
3 setLoading(false);
4});
5taxFormElement.on('success', ({data}) => {
6 const {
7  taxFormType,
8  taxFormId, 
9  signatureDate, 
10  signatureName, 
11  taxPayerExternalIdentifier} = data
12 // Handle event on submit action
13});
14
15taxFormElement.on('save', ({ data }) => {
16 // Handle event on save action
17 // Please note data format from save will be changed in future.
18});
19
20taxFormElement.on('error', e => {
21 // Handle event on error
22});
23taxFormElement.on('cancel', e => {
24 // Handle event when user cancel setup
25});

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.

Troubleshooting

For troubleshooting tips, see Airwallex.js error codes.