Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Use cases
Hold & convert funds
Connected accounts
Connected accounts overviewOnboard connected accounts
KYC and onboarding
Handle KYC RFI
KYB and onboarding
Handle Payment Enablement RFI
Embedded Payment Enablement RFI component
Hosted Payment Enablement RFI flowNative Payment Enablement RFI API
Onboard multiple connected accountsMove funds between accounts
Error codes

Embedded Payment Enablement RFI component

In some cases, Airwallex may request additional information relating to transactions from end users if more context is needed to process transactions in or out of the Airwallex account. The Embedded Transaction RFI component is a pre-built UI element that lets your clients provide this information with a single integration. Instead of building your own native flow, you can embed Airwallex’s information request flow directly in your own transaction dashboard or transaction processing experience.

Airwallex's embedded RFI form will display our operation team’s additional questions and collect the answers. You can also customize the visual appearance of the form to reflect your brand.

This page describes how to embed the Transaction RFI component into your page to ensure smooth processing of transactions with RFI requests.

How it works

The diagram below depicts the information flow in an Embedded Payment Enablement RFI component integration.

Embedded Payment Enablement RFI

Before you begin

Step 1: Get notified of an information request (RFI)

You can receive RFI notification via the following two methods:

Option 1: RFI webhook notification

Subscribe to our RFI webhook through the Airwallex web app to be notified when your account or one of your connected accounts receives a request for information.

JSON
Payload

Option 2: Query the RFI status via API

Call List all RFIs API to get a list of all open RFIs across your own account and connected accounts. If open RFIs are available, initialize the Payment Enablement RFI component SDK.

JavaScript
Initialize Payment Enablement RFI component SDK

Step 2: Initialize the components web SDK based on the RFI type

First, you will need to import the components-sdk and then initialize the environment. For details, see Initialize components SDK .

Set up the server for authentication

When the user begins the RFI process, you will need to get an authorization code to authorize them into the Embedded RFI workflow. Always get authorization code on the server side, a trusted environment. This prevents malicious users from being able to alter the scope.

When the RFI page loads, on your server, call Authorize a connected account API by providing the required fields in the request:

Shell
  • scope: Indicates the resources your application is allowed to access. For Embedded RFI regardless of the type, you must provide r:awx_action:rfi_view, w:awx_action:rfi_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.
JavaScript
JavaScript

The authorization_code is returned in the response, which you should then return to the client side as authCode in order to initialize the SDK.

Step 3: Add the Embedded Payment Enablement RFI component to your page

To embed the Payment Enablement RFI flow into your page, you will need to create an empty container, create the Payment Enablement RFI component and then mount the element to the container.

Define the Payment Enablement RFI container

First, create an empty container div with a unique id in your RFI page. Airwallex inserts an iframe into this div on mounting the element.

Create the Embedded Payment Enablement RFI component

To create the Payment Enablement RFI component, call createElement(type, options) and specify the type as paymentEnablementRfi. This method creates an instance of an individual component. Components are rendered as iframes.

You can also pass options in createElement() to overwrite styles and other functions. All properties are optional. For details, see Payment Enablement RFI component props .

JavaScript

Mount the element

Call element.mount() with the id of the div container to mount the element to the DOM. This builds an embedded Payment Enablement RFI workflow. The element should only be mounted once in a single onboarding flow.

JavaScript

For all the other methods supported on this component, see Element object methods .

Handle the ready event

Add the ‘ready’ event listener to ensure the Payment Enablement RFI component is rendered. It's recommended that you show a loading state UI before receiving the ‘ready’ event.

JavaScript

Step 4: Handle the response

Add success and error event listeners to handle error and success events received from Airwallex.

JavaScript

If no error occurred, display a message that the RFI was successful. If the RFI component fails with an error, display the appropriate message to your end user so they can take action and try again. See RFI Element events .

See table below for the common error codes and recommended next steps.

Error codeError messageNext steps
INIT_ERRORNo <parameter> providedCheck the params table for required init options.
INIT_ERRORFailed to authorizeConfirm that the clientId, env, codeVerifier and authCode passed in the init() function are valid.
INIT_ERRORAuth timeoutPlease check if your network connection is stable. If so, please contact Airwallex support.
UNAUTHORIZEDFailed to refresh tokenThe refreshToken might be expired (currently 1 hour). Please redo the entire flow to get a new authCode and initialize the SDK, and then create the element 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.
CREATE_ELEMENT_ERRORCreateElement with type <type> not supportedCheck the supported types
MOUNT_ELEMENT_ERRORCannot 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.
SUBMIT_FAILEDInternal API error: Failed to submit form.Please retry or contact Airwallex support.
UNKNOWNUnknown errorPlease retry or contact Airwallex support.
API_ERROR<API_name> API errorError occurred when calling internal API. Please retry or contact Airwallex support.
INVALID_KYC_STATUSInvalid KYC status: <kycStatus>Error occurred as account kycStatus is INIT or FAILURE, which is invalid for the user to enter the RFI flow
INVALID_RFI_STATUSInvalid RFI status: NO_ACTION_REQUIRED. No RFI session availableError occurred when there’s no open RFI.
- (Console message only)Please initialize Airwallex platform SDKPlease confirm if you have correctly loaded the SDK script using the init() function from our package or the CDN link.

Test your integration

You may test your integration for various success and error scenarios in the demo environment and then go live in the production environment. Contact your Airwallex Account Manager for test account details.

To trigger SDK errors during testing, use these instructions.

Error CodeHow to trigger
INIT_ERRORCall init() function with unsupported values for options, e.g., await init({env: 'other'}) where other is not supported
UNAUTHORIZEDInternal error, unable to trigger
AUTH_TIMEOUTBlock your network
CREATE_ELEMENT_ERRORCall createElement() function with unsupported element type, e.g., createElement('wrong_type')
MOUNT_ELEMENT_ERRORCall mount() method with a non-existent div id. e.g., element.mount('nonexistent-div-id')
SUBMIT_FAILEDInternal error, unable to trigger
UNKNOWNInternal error, unable to trigger
INVALID_RFI_STATUSCreate RFI component for an account, which does not have any open RFI
INVALID_KYC_STATUSCreate RFI component for a connected account with kycStatus of INIT or FAILURE

Example integrations

Explore a full, working code sample of an integration built using React .

FAQ

How do I customize the Embedded RFI component?

We can configure the RFI component to reflect your brand’s color palette and logo. Contact your Airwallex Account Manager to enable customization in line with your business requirements.

How do I handle re-entry?

If a user exits the RFI component then tries to re-enter the details later, you can handle re-entry based on ready and error events.

  • ready event: An open RFI is available and the user can enter the flow.
  • error event: Some error scenarios include:
    • INVALID_RFI_STATUS: There’s no open RFI for this account.
    • INVALID_KYC_STATUS: The account's kycStatus is INIT or FAILURE, which is invalid for the user to enter the RFI flow.

You should render error/status pages according to the event result. If you do not handle it, we will show the default status page with "You have no outstanding actions required".

JavaScript
On this page