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 KYC (Know Your Customer) information. After completing this quickstart, choose between Hosted Onboarding, Embedded Components, or Native API for your KYC 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-demo.airwallex.com for sandbox/demo, https://api.airwallex.com for production.

Shell

1curl -X POST https://api-demo.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-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      "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  }'

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    }
11  },
12  "primary_contact": {
13    "email": "[email protected]"
14  },
15  "customer_agreements": {
16    "agreed_to_data_usage": true,
17    "agreed_to_terms_and_conditions": true
18  },
19  "created_at": "2026-02-02T10:30:00Z"
20}

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-demo.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    }
12  },
13  "primary_contact": {
14    "email": "[email protected]"
15  },
16  "customer_agreements": {
17    "agreed_to_data_usage": true,
18    "agreed_to_terms_and_conditions": true
19  },
20  "created_at": "2026-02-02T10:30:00Z"
21}

The account remains in CREATED status until you collect and submit KYC 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 KYC review (after submitting KYC information).
ACTIVE: Account verified and fully operational (after successful KYC verification).
SUSPENDED: Account disabled or failed verification.

To transition the account from CREATED to ACTIVE, you need to collect KYC 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 KYC (Know Your Customer) verification before it can process transactions. To choose a KYC integration approach and build your production integration, see Plan your path to production.

Was this page helpful?