Platform relationships

Connected accounts exist within a three-tier structure: Airwallex provides the regulated financial infrastructure, your platform orchestrates operations and manages the customer relationship, and connected accounts are the accounts held by your customers. Understanding this structure is essential before you design your integration, because it determines how API calls are authorized, how funds move, and where compliance responsibilities lie.

The three-tier structure

At the infrastructure layer, Airwallex provides the banking rails, compliance processes, and regulatory licenses that make financial services possible. You interact with this layer through the Airwallex API using your platform's credentials.

Your platform sits in the middle. You create and manage connected accounts on behalf of your customers. Your platform is the entity that Airwallex contracts with and is accountable to. Airwallex has no direct relationship with your customers—only with you.

Connected accounts are the accounts your customers hold. Each connected account is provisioned in your customer's name, with its own wallet, its own verification state, and its own transaction history. Your platform controls what each account can do and orchestrates all operations on its behalf.

Acting on behalf of connected accounts

Platforms use the x-on-behalf-of header to call Airwallex APIs on behalf of a connected account. When you include a connected account's ID in this header, Airwallex treats the operation as if it originates from that account—debiting the connected account's wallet, crediting the connected account's wallet, or creating resources that belong to that account.

For example, to initiate a currency conversion on behalf of a connected account:

1curl -X POST https://api-demo.airwallex.com/api/v1/conversions/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -H 'x-on-behalf-of: {{CONNECTED_ACCOUNT_ID}}' \
5  -d '{
6    "buy_currency": "USD",
7    "sell_currency": "AUD",
8    "buy_amount": "10000",
9    "reason": "Settling invoices",
10    "request_id": "{{UNIQUE_REQUEST_ID}}",
11    "term_agreement": true
12  }'

This pattern is consistent across all APIs you can use on behalf of connected accounts, including Global Accounts, Conversions, Transfers, Connected Account Transfers, and Charges.

Funds movement between tiers

Two primary mechanisms move funds between your platform wallet and a connected account's wallet.

Connected Account Transfers API move funds from your platform's wallet to a connected account's wallet. Use them to distribute proceeds, pay commissions, or fund refunds—for example, distributing a seller's share after a marketplace sale settles. They can also move funds directly between two connected accounts.

Charges API move funds from a connected account's wallet to your platform's wallet. Use Charges to collect fees, service charges, or loan repayments. For example, to deduct your platform fee from a seller's balance before they withdraw earnings.

Beyond these two internal mechanisms, platforms can also trigger outbound payments from a connected account's wallet using the Transfers API—for example, when a customer wants to withdraw their balance to an external bank account.

See Wallets and funds flow for a full explanation of how money moves through the ecosystem.

Platform monetization

The platform model gives you several ways to generate revenue from connected accounts:

• Application fees on transfers: Charged when your platform initiates Connected Account Transfers on behalf of connected accounts.
• Foreign Exchange (FX) fees: Applied on top of Airwallex's base rate when customers convert currencies.
• Issuing interchange rebates: Shared with your platform on card transactions issued to your customers.
• Platform fees: Charged directly from a connected account's wallet using the Charges API API.

Your platform defines its own fee structures on top of the costs Airwallex charges you. The connected account model is designed to let you earn revenue from each financial operation your customers perform.

Responsibilities and boundaries

The three-tier structure defines a clear division of responsibility between Airwallex and your platform.

Your platform is responsible for the customer relationship. Airwallex does not interact directly with your customers—you collect the information Airwallex requires for compliance, submit it through the API, and manage the account from that point forward.

See Compliance and risk overview for a detailed breakdown of the compliance division of responsibility.