Native Cardholder RFI API
Learn how to use Airwallex's RFI API endpoints to build your own tailored experience for users to handle requests for information (RFI). These endpoints can be used directly for RFIs related to your own account, or RFIs related to your connected accounts (using the x-on-behalf-of header).
Before you begin
- To use RFI APIs for a connected account you will need the Native API OBO (On-Behalf-Of) permission enabled on your account. Please contact your Airwallex Account Manager to enable this if it is not already enabled.
- 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 cardholder RFIs across your account and connected accounts.
Step 2: Retrieve the RFI details
Call Retrieve an RFI API to retrieve the details of an RFI using the given RFI ID.
Automate responses
You can use values returned in questions.key field to automate RFI responses. questions.key is a unique coded value for each RFI scenario the question relates to.
The following codes are supported for the Cardholder RFI:
PROOF_OF_ADDRESS: If a question returns this key it requires an attached proof of address to be provided in the response. If this is already collected or stored on file you can automate a response to attach the relevant document.ID_COPY: If a question returns this key it requires an attached copy of the identification document for the cardholder to be provided in the response.
Examples of both of these question codes are shown within this guide for reference.
Step 3: Retrieve cardholder details
Cardholder RFI questions will be linked to a cardholder through the sources object in the RFI details. Call Retrieve a cardholder API using the cardholder ID returned in the sources.id field to retrieve details of the cardholder.
Step 4: Respond to the RFI
Call Respond to an RFI API to provide the information requested by Airwallex.
Step 5: Handle the response
Listen for status changes to the RFI via webhooks. See RFI events.
Error handling
| Error code | Message | Next steps |
|---|---|---|
invalid_state_for_operation | - | Make sure the RFI status is ACTION_REQUIRED |
account_not_authorised_for_operation | - | Make sure the RFI is linked to the correct account |
resource_not_found | - | Make sure you are using the correct RFI ID when querying |
invalid_argument | Please answer all questions in the request/ Please provide your answers in the right format (TEXT vs ATTACHMENT) | Make sure all the RFI questions are answered / and in the right format |