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.
Download and install the
@airwallex/components-sdkpackage using Yarn or NPM:yarn add @airwallex/components-sdkornpm install @airwallex/components-sdk
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 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 Onboarding, you must providew:awx_action:transfers_editas the scope.code_challenge: Generate a challenge token together with thecode_verifierusing 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 generatecode_verifierandcode_challengeor 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.
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.
Initialize Airwallex Components 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.
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.
Create the Embedded Tax Form component
You can use the theme builder button at the bottom right corner of the demo site to get the corresponding options.
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.
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 Tax Form component.
Common errors
| ERROR CODE | ERROR MESSAGE | NEXT STEP |
|---|---|---|
| INIT_ERROR | No {parameter} provided | Check the params table for required init options. |
| INIT_ERROR | Failed to authorize | Confirm that the clientId, env, codeVerifier, and authCode passed in the init() function are valid. |
| INIT_ERROR | Auth timeout | Please check if your network connection is stable. If so, please contact Airwallex support. |
| UNAUTHORIZED | Failed to refresh token | The refreshToken might be expired (currently 1 hour). Please redo the entire flow to get a new authCode and initialize the SDK, then create the element again. |
| CREATE_ELEMENT_ERROR | Please init() before createElement() | Please confirm you have correctly loaded the SDK script using the init() function from our package or the CDN link. |
| CREATE_ELEMENT_ERROR | CreateElement with {type} not supported | Please check the supported types. |
| MOUNT_ELEMENT_ERROR | Cannot find element with dom element id: {id} | Please check if the container dom id or the dom element passed in the mount() function is valid. |
| ELEMENT_NOT_FOUND | The mount container does not exist | Please check if the container dom id or the dom element passed in the mount() function is valid. |
| FAILED_LOAD_SCRIPT | Failed to load Airwallex SDK scripts: ${url} | Please check your network and try again. |
Form event type
| EVENT NAME | DESCRIPTION | EVENT DATA TYPE |
|---|---|---|
| ready | This event will be fired when the page is ready. | { elementType: 'taxForm' } |
| success | This event fires when tax form is submitted successfully. | { taxFormType: string; taxFormId: string; signatureDate: string; signatureName: string; identifier: string } |
| save | This event fires when the tax form is saved and exists. | { data: object } |
| error | This event fires when an error occurs within the element. | { code: ELEMENT_ERROR_CODE; message: string } |
Element error code
| ERROR CODE | ERROR MESSAGE | NEXT STEP |
|---|---|---|
| REQUEST_ERROR | UNAUTHORIZED | The refreshToken might be expired (currently 1 hour). Please redo the entire flow to get a new authCode and initialize the SDK, then create the element again. |
| REQUEST_ERROR | string | Please check the params are valid before you submit the form. |