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.

Payload

JSON
1{
2 "id": "0a963b8c-c292-48b0-bc96-a424a3cfea6f",
3 "name": "rfi.action_required",
4 "account_id": "acct_e_2wbiZ3Mx-ynlX-7Qidbg",
5 "data": {
6   "id": "a72f3483-d600-4d9a-a051-bcbe5126a4b4"
7 },
8 "created_at": "2023-04-11T07:29:36+0000",
9 "version": "2023-03-31"
10}

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.

Example request

Shell
1curl --request GET 
2--url 'https://api-demo.airwallex.com/api/v1/rfis?statuses=ACTION_REQUIRED&types=CARDHOLDER&end_created_at=2023-07-01T01:20:33+0000&from_created_at=2023-06-01T01:20:33+0000' 
3--header 'Content-Type: application/json' 
4--header 'Authorization: Bearer <your_bearer_token>'

Example response

JSON
1{
2  "items": [
3    {
4      "account_id": "acct_e_2wbiZ3Mx-ynlX-7Qidbg",
5      "active_request": {
6        "created_at": "2023-04-12T07:29:36+0000",
7        "questions": [
8          {
9            "answer": {
10              "type": "ATTACHMENT"
11            },
12            "comment": "Please provide more information",
13            "description": {
14              "en": "Please provide a document confirming the residential address of Jack Ma, such as: - ID documents containing addresses - Bank statement within 3 months - Utility bill within 3 months - Current lease agreement - Resident Permit",
15              "zh": "请提供Jack Ma居住地址的证明文件，例如： - 包含地址的身份证件 - 3个月内的银行对账单 - 3个月内的水电费账单 - 有效的租赁协议"
16            },
17            "id": "ba7bfb51-77bc-4991-b651-0969ece1d263",
18            "title": {
19              "en": "Proof of Residential Address",
20              "zh": "个人地址证明"
21            },
22            "key": "PROOF_OF_ADDRESS",
23            "sources": [
24              {
25                "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
26                "type": "CARDHOLDER"
27              }
28            ]
29          },
30          {
31            "answer": {
32              "type": "IDENTITY_DOCUMENT"
33            },
34            "comment": "Please provide more information",
35            "description": {
36              "en": "Please provide a copy of a valid government-issued ID to verify the identity of Jack Ma. Acceptable identification documents include Passport, Driver Licence or National ID (front and back).",
37              "zh": "请提供以下个人的政府签发的有效身份证（正反面）或护照副件：Jack Ma"
38            },
39            "id": "3eb6693a-3793-41d8-9937-3648a11722d7",
40            "title": {
41              "en": "Identification Document",
42              "zh": "身份证件"
43            },
44            "key": "ID_COPY",
45            "sources": [
46              {
47                "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
48                "type": "CARDHOLDER"
49              }
50            ]
51          }
52        ],
53        "updated_at": "2023-04-14T07:29:36+0000"
54      },
55      "answered_requests": [
56        {
57          "created_at": "2023-04-12T07:29:36+0000",
58          "questions": [
59            {
60              "answer": {
61                "attachments": [
62                  {
63                    "file_id": "418ce9e9-c370-52bd-8192-e78283770c43"
64                  }
65                ],
66                "type": "ATTACHMENT"
67              },
68              "description": {
69                "en": "Please provide a document confirming the residential address of Jack Ma, such as: - ID documents containing addresses - Bank statement within 3 months - Utility bill within 3 months - Current lease agreement - Resident Permit",
70                "zh": "请提供Jack Ma居住地址的证明文件，例如： - 包含地址的身份证件 - 3个月内的银行对账单 - 3个月内的水电费账单 - 有效的租赁协议"
71              },
72              "id": "ba7bfb51-77bc-4991-b651-0969ece1d263",
73              "title": {
74                "en": "Proof of Residential Address",
75                "zh": "个人地址证明"
76              },
77              "key": "PROOF_OF_ADDRESS",
78              "sources": [
79                {
80                  "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
81                  "type": "CARDHOLDER"
82                }
83              ]
84            }
85          ],
86          "updated_at": "2023-04-14T07:29:36+0000"
87        }
88      ],
89      "created_at": "2023-04-11T07:29:36+0000",
90      "id": "a72f3483-d600-4d9a-a051-bcbe5126a4b4",
91      "status": "ACTION_REQUIRED",
92      "type": "CARDHOLDER",
93      "updated_at": "2023-04-12T07:29:36+0000"
94    }
95  ],
96  "page_after": "YWZ0ZXI9MTdiYTVhYzktM2FiMC00NmIzLWE4ODctMTNjNmU5NTg2N2Qy",
97  "page_before": "YmVmb3JlPTg0NDg0ODIwLTU0N2UtNDc5YS1iMTY3LTgzYjQwMzcwODQ2ZQ=="
98}

Step 2: Retrieve the RFI details

Call Retrieve an RFI API to retrieve the details of an RFI using the given RFI ID.

Example request

Shell
1curl --request GET
2--url 'https://api-demo.airwallex.com/api/v1/rfis/a72f3483-d600-4d9a-a051-bcbe5126a4b4'
3--header 'Authorization: Bearer <your_bearer_token>'
4

Example response

JSON
1{
2  "account_id": "acct_e_2wbiZ3Mx-ynlX-7Qidbg",
3  "active_request": {
4  "created_at": "2023-04-12T07:29:36+0000",
5    "questions": [
6      {
7        "answer": {
8          "type": "ATTACHMENT"
9        },
10        "comment": "Please provide more information",
11        "description": {
12          "en": "Please provide a document confirming the residential address of Jack Ma, such as: - ID documents containing addresses - Bank statement within 3 months - Utility bill within 3 months - Current lease agreement - Resident Permit",
13          "zh": "请提供Jack Ma居住地址的证明文件，例如： - 包含地址的身份证件 - 3个月内的银行对账单 - 3个月内的水电费账单 - 有效的租赁协议"
14        },
15        "id": "ba7bfb51-77bc-4991-b651-0969ece1d263",
16        "title": {
17          "en": "Proof of Residential Address",
18          "zh": "个人地址证明"
19        },
20        "key": "PROOF_OF_ADDRESS",
21        "sources": [
22          {
23            "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
24            "type": "CARDHOLDER"
25          }
26        ]
27      },
28      {
29       "answer": {
30           "type": "IDENTITY_DOCUMENT"
31         },
32       "comment": "Please provide more information",
33       "description": {
34           "en": "Please provide a copy of a valid government-issued ID to verify the identity of Jack Ma. Acceptable identification documents include Passport, Driver Licence or National ID (front and back).",
35           "zh": "请提供以下个人的政府签发的有效身份证（正反面）或护照副件：Jack Ma"
36       },
37       "id": "3eb6693a-3793-41d8-9937-3648a11722d7",
38       "title": {
39           "en": "Identification Document",
40           "zh": "身份证件"
41       },
42       "key": "ID_COPY",
43       "sources": [
44           {
45         "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
46         "type": "CARDHOLDER"
47           }
48       ]
49   }
50    ],
51    "updated_at": "2023-04-14T07:29:36+0000"
52  },
53  "answered_requests": [
54    {
55      "created_at": "2023-04-12T07:29:36+0000",
56      "questions": [
57        {
58          "answer": {
59            "attachments": [
60              {
61                "file_id": "418ce9e9-c370-52bd-8192-e78283770c43"
62              }
63            ],
64            "type": "ATTACHMENT"
65          },
66          "comment": "Please provide more information",
67          "description": {
68            "en": "Please provide a document confirming the residential address of Jack Ma, such as: - ID documents containing addresses - Bank statement within 3 months - Utility bill within 3 months - Current lease agreement - Resident Permit",
69            "zh": "请提供Jack Ma居住地址的证明文件，例如： - 包含地址的身份证件 - 3个月内的银行对账单 - 3个月内的水电费账单 - 有效的租赁协议"
70          },
71          "id": "ba7bfb51-77bc-4991-b651-0969ece1d263",
72          "title": {
73            "en": "Proof of Residential Address",
74            "zh": "个人地址证明"
75          },
76          "key": "PROOF_OF_ADDRESS",
77          "sources": [
78            {
79              "id": "8afa0deb-4df7-47b6-b285-3bf130421976",
80              "type": "CARDHOLDER"
81            }
82          ]
83        }
84      ],
85      "updated_at": "2023-04-14T07:29:36+0000"
86    }
87  ],
88  "created_at": "2023-04-11T07:29:36+0000",
89  "id": "a72f3483-d600-4d9a-a051-bcbe5126a4b4",
90  "status": "ACTION_REQUIRED",
91  "type": "CARDHOLDER",
92  "updated_at": "2023-04-12T07:29:36+0000"
93}

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.

Example request

Shell
1curl --request POST 
2--url 'https://api-demo.airwallex.com/api/v1/rfis/a72f3483-d600-4d9a-a051-bcbe5126a4b4/respond' 
3--header 'Content-Type: application/json' 
4--header 'Authorization: Bearer <your_bearer_token>' 
5--data '{
6  "questions": [
7    {
8      "answer": {
9        "attachments": [
10          {
11            "file_id": "418ce9e9-c370-52bd-8192-e78283770c43"
12          }
13        ]
14      },
15      "id": "ba7bfb51-77bc-4991-b651-0969ece1d263"
16    },
17    {
18      "answer": {
19        "identity_document": {
20          "front_file_id": "87c1ae52-c952-4117-9ed0-695c88883897",
21          "back_file_id": "93d2657b-e281-4da8-9c14-adf69243a270",
22          "issuing_country": "CN",
23          "type": "IDENTITY_CARD"
24        }
25      },
26      "id": "3eb6693a-3793-41d8-9937-3648a11722d7"
27    }
28  ]
29}'

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

Was this page helpful?