Native API

To onboard connected accounts using the native API, complete the steps in this document. Onboarding verification, previously referred to as Know Your Customer (KYC), is the process by which Airwallex verifies the identity of a connected account holder. The native API gives you complete control over the onboarding experience: you build your own UI and use Airwallex APIs to collect and submit identity information directly.

Before you begin

Ensure you have the following before you start:

• An access token API for your Airwallex account.
• Familiarity with the onboarding verification requirements for business and individual accounts.

Create a connected account

Call Create a connected account API to create the account. Connected accounts created through this endpoint are linked to your platform, and you are authorized to transact on their behalf using Airwallex's Accounts APIs.

By confirming agreement to Airwallex's terms and conditions, your platform consents to the terms covering the relationship between Airwallex, your business, and the connected account. This authorizes Airwallex to act on the account according to your instructions.

1curl -X POST https://api-demo.airwallex.com/api/v1/accounts/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "account_details": {
6      "business_details": {
7        "business_name": "your_business_name"
8      }
9    },
10    "customer_agreements": {
11      "agreed_to_data_usage": true,
12      "agreed_to_terms_and_conditions": true
13    },
14    "primary_contact": {
15      "email": "[email protected]"
16    }
17  }'

Save the account_id returned in the response—you use it in the following steps.

Update and submit the account for onboarding

Determine required data

Review the onboarding verification requirements for business and individual accounts to identify the fields you need to collect.

All required fields must be filled before activating the account. Filling in optional fields before activation increases the success rate. Collect the required fields from account holders using your interface, or use information previously collected or determined from your own data (for example, monthly transaction volumes).

You can create an empty account and update the required information in stages. To do so, create a minimal account first — you only need three fields:

• Primary contact (email or mobile phone number)
• Agreement to data sharing
• Agreement to terms and conditions

1curl -X POST https://api-demo.airwallex.com/api/v1/accounts/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "account_details": {
6      "legal_entity_type": "INDIVIDUAL"
7    },
8    "customer_agreements": {
9      "agreed_to_data_usage": true,
10      "agreed_to_terms_and_conditions": true
11    },
12    "primary_contact": {
13      "email": "[email protected]"
14    }
15  }'

Example response

1{
2  "id": "acct_44ymLf86OR2pMWjCRLGWSw",
3  "status": "CREATED",
4  "requirements": {},
5  "account_details": {
6    "legal_entity_type": "INDIVIDUAL",
7    "individual_details": {
8      "first_name": "Rob",
9      "last_name": "Stark"
10    }
11  },
12  "customer_agreements": {
13    "agreed_to_data_usage": true,
14    "agreed_to_terms_and_conditions": true,
15    "opt_in_for_marketing": false
16  },
17  "primary_contact": {
18    "email": "[email protected]",
19    "mobile": "12345678901"
20  }
21}

Attach data and documents

Upload documents to the Airwallex server using the File service API. Save the file_id returned in the response so you can reference it when updating the account. Once all documents are uploaded, proceed to the next step.

The optional notes query parameter lets you label the uploaded file for your own reference (for example, notes=passport-front).

1curl -X POST https://files-demo.airwallex.com/api/v1/files/upload?notes=passport-front \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: multipart/form-data' \
4  -F 'file=@/path/to/passport.pdf'

Example response

1{
2  "created": 1597914782,
3  "file_id": "NWRiYjUzMTItNWY2MC00MDNiLWE4ZmUtOTllYjRjZGZhZmU4LHwsc2hlbnpoZW4sfCw0LjLvvIlHTFDkuJrliqHpnIDmsYIgJiBBV1jlr7nmjqXmlrnmoYggMTIuMjAueGxzeA",
4  "filename": "string",
5  "notes": "string",
6  "object_type": "string",
7  "size": 0
8}

Call Update a connected account API to add the collected information to the account. Replace the account_id in the URL path with the value returned when you created the account. You can call this endpoint as many times as needed until all required information has been added — it can also be used to overwrite previously submitted information.

1curl -X POST https://api-demo.airwallex.com/api/v1/accounts/acct_44ymLf86OR2pMWjCRLGWSw/update \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "account_details": {
6      "legal_entity_type": "INDIVIDUAL",
7      "individual_details": {
8        "nationality": "AU",
9        "date_of_birth": "1980-10-10",
10        "address": {
11          "address_line1": "200 Collins Street",
12          "address_line2": "200 Collins Street",
13          "country_code": "AU",
14          "postcode": "3000",
15          "state": "VIC",
16          "suburb": "Melbourne"
17        },
18        "primary_identification": {
19          "identification_type": "PASSPORT",
20          "issuing_country_code": "AU",
21          "passport": {
22            "front_file_id": "NWRiYjUzMTItNWY2MC00MDNiLWE4ZmUtOTllYjRjZGZhZmU4LHwsc2hlbnpoZW4sfCw0LjLvvIlHTFDkuJrliqHpnIDmsYIgJiBBV1jlr7nmjqXmlrnmoYggMTIuMjAueGxzeA",
23            "passport_number": "PA1234567",
24            "expire_at": "2028-06-30",
25            "effective_at": "2020-01-15",
26            "mrz_line1": "PAAUSTARKROB<<<<<<<<<<<<<<<<<<<<<<<<<<<<<",
27            "mrz_line2": "PA12345678AUS8010101M2806305<<<<<<<<<<<<6"
28          }
29        }
30      }
31    }
32  }'

The nationality field accepts ISO 3166-1 alpha-2 country codes (for example, "AU" for Australia). The mrz_line1 and mrz_line2 fields are optional — include them only if MRZ data is available from the document scan.

Submit the account for activation

After collecting all required information, call Submit account for activation API. If the information meets the requirements, the account status updates to SUBMITTED. This status indicates the account is pending review — there is no separate onboarding verification resource; the verification state is reflected through the account status field.

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

Subscribe to account status webhooks to be notified when the status changes. Review time varies by platform and account type. Alternatively, call Get account by ID API to check the status field at any time.

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

After submission, the account can transition to one of the following statuses:

• ACTIVE — Onboarding verification was successful. The account is ready to use.
• ACTION_REQUIRED — Additional information is needed. Airwallex issues a request for information (RFI); respond using Handle onboarding verification RFIs.
• SUSPENDED — Onboarding verification was unsuccessful. No further action can be taken by the platform or the account holder.

If the submitted information does not meet the requirements, Submit account for activation API returns a 400 error. Possible error codes: field_required, invalid_argument.

Example error response

1{
2  "code": "invalid_argument",
3  "message": "ensure identification type is one of [DRIVERS_LICENSE, PASSPORT, PERSONAL_ID, MEDICARE_CARD]",
4  "source": "account_details.individual_details.primary_identification.identification_type"
5}

Handle requests for information (RFI)

Additional steps may be required to complete account activation, even if the information submitted in Update and submit the account for onboarding was initially sufficient. There are generally two reasons this can occur:

• Failed identity verification: Airwallex was unable to verify the account holder's identity. Ask the account holder to submit a second form of identification, or retry after correcting errors in the previously submitted data.
• Additional information requests: Airwallex requires more information to assess the account holder's risk profile before the account can be activated.

For guidance on responding to RFIs, see Handle onboarding verification RFIs.

Next steps

Now that you have submitted the connected account for onboarding verification, you can:

• Handle onboarding verification RFIs if Airwallex requests additional information.
• Start payment activation verification if your connected account will act as merchant of record.