Hosted Payment Enablement RFI flow
In some cases, Airwallex may request additional information relating to enablement of payment-related capabilities. The hosted payment enablement RFI component 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 users. You can also customize the visual appearance of the 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 account via an API.
- Direct the 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 user is automatically redirected back into your environment (or to any return URL of your choice as provided when creating the hosted flow instance).
Before you begin
- Contact your Airwallex Account Manager to:
- Enable connected account RFI using Hosted flow. The Account Manager will create a hosted flow template and will provide you with the template open ID (to be used in Step 2).
- Customize your hosted flow main landing page for business name, logo and color. Note that the customized logo will appear on all hosted flow pages.
- 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.
Step 1: Get notified of an information request (RFI)
You can receive RFI notifications 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.
Option 2: Query the RFI status via API
Call List all RFIs API to get a list of all open Payment Enablement RFIs across your accounts, your own account and connected accounts.
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 (
templatenot found,account_idnot found) - 403 (not authorized for this action/account, account status is SUSPENDED, i.e., disabled or failed KYC)
- 500 (server error)
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:
- Check if a saved hosted flow instance ID for the account exists (from Step 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.
- 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 code | Message | Next steps |
|---|---|---|
TOKEN_EXPIRED | Authorization code has expired | Re-authorize the user (see Step 3) using the saved hosted flow instance ID |
UNAUTHORISED | Unauthorised. Invalid token also results in this error | Authorize 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_STATUS | Action of hosted flow instance has a status that is not valid to operate on | Unrecoverable error. For example, the account’s KYC application is rejected or RFI status is closed. |
FLOW_INSTANCE_NOT_FOUND | Hosted flow instance is not found | Create a new hosted flow instance as described in Step 2 |
SUBMIT_FAILED | KYC submission failure | Retry submission if network error or contact Airwallex support. |
UNKNOWN | Unidentified errors | Contact Airwallex support |