Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewUnderstanding Banking as a ServiceMarket & infrastructure coverage
Get started
Connected accounts
Connected accounts overviewKYC and onboarding
Handle KYC RFI
Hosted KYC RFI flow
Embedded KYC RFI componentNative KYC RFI API
Onboard multiple connected accountsMove funds between accounts
Error codes
Test and go live

Hosted KYC RFI flow

In some cases, Airwallex may request additional information from end users if the information initially provided during KYC is deemed insufficient to approve the application. Hosted RFI enables you as a platform to redirect end users to an Airwallex-hosted web form to provide this additional information. This means you can deal with those requests without having to build your own full-fledged form using Airwallex APIs.

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

The hosted RFI flow includes these three simple steps:

  • Retrieve a secure, short-lived hosted flow link unique to each connected account via an API
  • Direct the end user who clicks on the link into an Airwallex-hosted environment to complete a white-labeled additional information form
  • After the form is complete, the end user is automatically redirected back into your environment (or to any return URL of your choice as provided when creating the hosted flow instance).

Explore the end user experience of completing the hosted flow on the demo environment .

Before you begin

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

You can receive RFI notification via the following two methods:

Option 1: RFI webhook notification

Subscribe to our RFI webhook 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 accounts.

Shell
Example request
JSON
Example response

Step 2: Create a hosted flow instance

Create a hosted flow instance for an account, your own account or a connected account. Specify the account_id for which you are creating the flow and the hosted flow template id as provided by Airwallex. You will also need to specify a return_url to which the customer will be redirected once the flow is complete.

A successful request returns a hosted flow URL (url) and a hosted flow instance ID (id). The URL must not be shared with the customer until it’s authorized by you to ensure that it’s only intended for this customer.

Make sure to save the hosted flow instance ID mapped to the account.

Error responses could include:

  • 400 (template not found, account_id not found)
  • 403 (not authorized for this action/account, account status is SUSPENDED, i.e., disabled or failed KYC)
  • 500 (server error)
Shell
Example request
JSON
Example response

Step 3: Authorize the user into the hosted flow

Call Authorize the flow API using the hosted flow instance id (returned in the previous request) to authorize the URL. The authorized url returned in the authorization response is short-lived so it’s highly recommended that you redirect the customer as quickly as possible.

The customer can choose to respond to any of the open RFIs displayed on the page.

Error responses could include:

  • 400 (hosted flow already finished)
  • 403 (not authorized for this action/account/flow)
  • 404 (hosted flow instance ID not found)
  • 500 (server error)
Shell
Example request
JSON
Example response

Step 4: Handle session timeout

Session timeouts may occur due to inactivity or if the user exits the hosted flow without completing the form. If the session has expired, we will show a session prompt that lasts for 60 seconds before we log the user out with error code TOKEN_EXPIRED.

The user may return to the form to complete the information after a session expiry. To handle this scenario:

  1. Check if a saved hosted flow instance ID for the account exists (from Step 2).
  2. If the account has a saved hosted flow, re-authorize the user (Step 3). Call Authorize the flow API to retrieve a link with a new authorization code.
  3. Redirect the user to the new URL from the response.

Step 5: Handle response

Listen for status changes to the account/transaction via webhooks. See webhook events.

Error handling

Error codeMessageNext steps
TOKEN_EXPIREDAuthorization code has expiredRe-authorize the user (see Step 3) using the saved hosted flow instance ID
UNAUTHORISEDUnauthorised. Invalid token also results in this errorAuthorize the user (see Step 3) using the saved hosted flow instance ID. If the user has Airwallex web app access, please try opening the hosted flow link in incognito mode.
INVALID_ACTION_STATUSAction of hosted flow instance has a status that is not valid to operate onUnrecoverable error. For example, the account’s KYC application is rejected or RFI status is closed.
FLOW_INSTANCE_NOT_FOUNDHosted flow instance is not foundCreate a new hosted flow instance as described in Step 2
SUBMIT_FAILEDKYC submission failureRetry submission if network error or contact Airwallex support.
UNKNOWNUnidentified errorsContact Airwallex support
On this page