Quickstart: Your first connected account

Copy for LLMView as Markdown

This quickstart guides you through creating your first connected account using the Airwallex API. You'll learn how to authenticate, create an account, and check its status. This provides the foundation for building your full connected accounts integration.

This quickstart creates a basic connected account. To fully activate the account for transactions, you'll need to collect and submit identity information for onboarding verification—previously referred to as Know Your Customer (KYC). After completing this quickstart, choose between Hosted Onboarding, Embedded Components, or Native API for your onboarding verification integration.

Before you begin

Ensure you have:

An Airwallex platform account with connected accounts capabilities enabled. If you don't have one, contact your Airwallex Account Manager.
API credentials. You'll need your client ID and API key.
Access to the sandbox environment for testing.
Basic familiarity with making API requests using cURL, Postman, or your preferred HTTP client.

New to Airwallex? If you're not yet set up, reach out to your Account Manager to enable connected accounts on your account and get your API credentials.

Step 1: Authenticate and get an access token

All API requests require authentication. First, obtain an access token using your API credentials.

Environment URLs: The base URL depends on your environment. Use https://api.sandbox.airwallex.com for sandbox/demo, https://api.airwallex.com for production.

Shell

1curl -X POST https://api.sandbox.airwallex.com/api/v1/authentication/login \
2  -H 'Content-Type: application/json' \
3  -H 'x-client-id: YOUR_CLIENT_ID' \
4  -H 'x-api-key: YOUR_API_KEY'

JSON

1{
2  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "expires_at": "2026-02-02T12:00:00Z"
4}

Save the token value—you'll use it in subsequent API requests as a Bearer token in the Authorization header.

Access tokens expire after 30 minutes. In production, implement token refresh logic to maintain uninterrupted API access.

Step 2: Create a connected account

Create a connected account for an individual customer using the Create connected account API endpoint.

This quickstart creates a connected account for an individual. You must agree to Airwallex's terms and conditions on behalf of the account holder before creating the account.

Shell

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

JSON

1{
2  "id": "acct_hkdmCy9wnfEJjMHNxINdC",
3  "status": "CREATED",
4  "account_details": {
5    "legal_entity_type": "INDIVIDUAL",
6    "individual_details": {
7      "first_name": null,
8      "last_name": null,
9      "nationality": null,
10      "residential_address": {
11        "country_code": "AU"
12      }
13    }
14  },
15  "primary_contact": {
16    "email": "[email protected]"
17  },
18  "customer_agreements": {
19    "agreed_to_data_usage": true,
20    "agreed_to_terms_and_conditions": true
21  },
22  "created_at": "2026-02-02T10:30:00Z"
23}

The response shows:

A connected account created with status CREATED.
The account ID starts with acct_ prefix.
The account is ready to be updated with additional details for identity verification.

Save the account ID: Store the id value (acct_hkdmCy9wnfEJjMHNxINdC in this example) - you'll use it to update account details, check verification status, and manage the account.

Step 3: Check account status

Check the connected account's status using the Get connected account API endpoint.

Shell

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

JSON

1{
2  "id": "acct_hkdmCy9wnfEJjMHNxINdC",
3  "status": "CREATED",
4  "account_details": {
5    "legal_entity_type": "INDIVIDUAL",
6    "individual_details": {
7      "first_name": null,
8      "last_name": null,
9      "nationality": null,
10      "date_of_birth": null,
11      "residential_address": {
12        "country_code": "AU"
13      }
14    }
15  },
16  "primary_contact": {
17    "email": "[email protected]"
18  },
19  "customer_agreements": {
20    "agreed_to_data_usage": true,
21    "agreed_to_terms_and_conditions": true
22  },
23  "created_at": "2026-02-02T10:30:00Z"
24}

The account remains in CREATED status until you collect and submit identity information. The account status field transitions through these values as the account lifecycle progresses:

CREATED: Account created but not yet submitted for verification (current status).
SUBMITTED: Account submitted for onboarding verification review (after submitting identity information).
ACTIVE: Account verified and fully operational (after successful onboarding verification).
SUSPENDED: Account disabled or failed verification.

To transition the account from CREATED to ACTIVE, you need to collect identity information from the account holder and submit it for verification. See the Next steps section below for integration options.

You can also subscribe to account status webhooks to be notified of status changes automatically.

Next steps

You've successfully created your first connected account. The account is in CREATED status and needs onboarding verification—previously referred to as Know Your Customer (KYC)—before it can process transactions. To choose an onboarding verification integration approach and build your production integration, see Plan your path to production.

Was this page helpful?