Simulate an onboarding verification RFI

Airwallex may issue an onboarding verification RFI after a connected account is submitted for activation, when compliance needs more information before the account can become ACTIVE. Until the review completes, the account cannot be activated. This page walks through simulating that scenario end to end so you can test how your integration onboards an account, handles the RFI, and responds to the final outcome.

For the underlying simulation API reference, see Simulate RFI sessions. For production RFI handling, see Handle onboarding verification RFIs.

Flow overview

1. Create an account and submit it for review.
2. Simulate an onboarding verification RFI being raised against it.
3. Receive the rfi.action_required webhook, fetch the RFI, and present the questions to your user.
4. Submit the answer and close the RFI.
5. Simulate the onboarding review approving the account and confirm it reaches ACTIVE.

Before you begin

• Complete the sandbox setup and obtain an access token.
• Subscribe a webhook endpoint to the rfi.action_required, rfi.answered, and rfi.closed RFI webhook events.

Create and submit an account

Create a connected account and submit it for review so it reaches SUBMITTED. An onboarding verification RFI can only be raised against a submitted account. For create and submit details, see Simulate connected account status transition.

Save the account id from the create response for the x-on-behalf-of header in later steps.

Simulate an onboarding verification RFI

Call Create an RFI API with type: "KYC". The example below requests a single text answer; omit questions to use the default question set.

1curl -X POST https://api-demo.airwallex.com/api/v1/simulation/rfis/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "type": "KYC",
6    "questions": [
7      {
8        "answer": {
9          "type": "TEXT"
10        }
11      }
12    ]
13  }'

The response has type: "KYC" and status ACTION_REQUIRED, with sources referencing your account.

Receive the webhook and fetch the RFI

Your endpoint receives an rfi.action_required event. Read the RFI ID from the data.id field, then retrieve the full RFI to read the questions.

1curl https://api-demo.airwallex.com/api/v1/rfis/{{RFI_ID}} \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Present the questions to your user and note each question_id for the response.

Submit the response and close the RFI

Submit the answer, mapping it to its question_id. The RFI moves to ANSWERED and you receive an rfi.answered webhook.

1curl -X POST https://api-demo.airwallex.com/api/v1/rfis/{{RFI_ID}}/respond \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "questions": [
6      {
7        "id": "{{QUESTION_ID}}",
8        "answer": {
9          "type": "TEXT",
10          "text": "Salary income"
11        }
12      }
13    ]
14  }'

Then simulate the review being resolved by calling Close an RFI API. The RFI moves to CLOSED and you receive an rfi.closed webhook.

1curl -X POST https://api-demo.airwallex.com/api/v1/simulation/rfis/{{RFI_ID}}/close \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Confirm the account outcome

Closing the RFI resolves the information request but does not activate the account. To simulate the onboarding review approving the account, transition it to ACTIVE.

1curl -X POST https://api-demo.airwallex.com/api/v1/simulation/accounts/{{ACCOUNT_ID}}/update_status \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "force": true,
6    "next_status": "ACTIVE"
7  }'

Confirm the final status:

1curl https://api-demo.airwallex.com/api/v1/accounts/{{ACCOUNT_ID}} \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

In production, your integration learns the outcome from the account's own status updates, not from the RFI close event.

Variant: request an identity document

To request a document instead of free text, create the RFI with an IDENTITY_DOCUMENT question:

1curl -X POST https://api-demo.airwallex.com/api/v1/simulation/rfis/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "type": "KYC",
6    "questions": [
7      {
8        "answer": {
9          "type": "IDENTITY_DOCUMENT"
10        }
11      }
12    ]
13  }'

Upload the document to obtain file IDs, then respond with the structured identity_document answer:

1curl -X POST https://api-demo.airwallex.com/api/v1/rfis/{{RFI_ID}}/respond \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "questions": [
6      {
7        "id": "{{QUESTION_ID}}",
8        "answer": {
9          "type": "IDENTITY_DOCUMENT",
10          "identity_document": {
11            "front_file_id": "{{FRONT_FILE_ID}}",
12            "back_file_id": "{{BACK_FILE_ID}}",
13            "type": "PASSPORT",
14            "issuing_country": "AU",
15            "number": "{{DOCUMENT_NUMBER}}"
16          }
17        }
18      }
19    ]
20  }'

Related

• Simulate RFI sessions
• Simulate a Transaction RFI
• Handle onboarding verification RFIs