Device tracking

Establish a persistent device–account link for platform/connected accounts API interactions using Risk SDK.

Device tracking links your end customers' devices to Airwallex API calls. This is required for compliance and fraud prevention when building a platform integration with connected accounts.

This guide is for platform developers integrating Airwallex Connected Accounts into web or mobile applications.

How device tracking works

When your end customers interact with your platform, device tracking captures a unique device identifier. You then include this identifier in API requests to Airwallex using the x-risk-device-id header. This allows Airwallex to associate API calls with specific devices for fraud detection and regulatory compliance.

Key concepts:

Platform: Your company or application (Airwallex's customer).
Connected account: Your end customer (a business or individual using your platform).
Device tracking: Links your end customer's device to Airwallex API calls.

Web integration

For platforms where end customers interact through desktop browsers, mobile browsers, or app webviews.

Step 1: Load the device tracking script

Add the following script tag to the <head> or <body> of every HTML page. The script loads asynchronously and will not block user interactions.

HTML

1<script
2  id="awx-webapp-device-api"
3  src="https://static.airwallex.com/webapp/fraud/device-fingerprint/webapp.js"
4  data-tenant="YOUR-PLATFORM-NAME"
5  async
6></script>

Replace YOUR-PLATFORM-NAME with a unique identifier for your platform among all Airwallex customers. If you have multiple websites under one platform, you can use the same name.

Environment URLs:

Environment	SDK URL
Production	`https://static.airwallex.com/webapp/fraud/device-fingerprint/webapp.js`
Demo (Testing)	`https://static-demo.airwallex.com/webapp/fraud/device-fingerprint/webapp.js`

Step 2: Retrieve the device ID from the browser

After the script loads, it generates a device ID and saves it in the browser's localStorage and cookies. Retrieve this ID as follows:

JavaScript

1import Cookies from 'js-cookie';
2
3const AirwallexDeviceId =
4  localStorage.getItem('AWX_RISK_ID') ||
5  Cookies.get('AWX_RISK_ID');
6
7// Pass the device ID to your platform server

Always try to get the device ID from localStorage first. If unavailable, fall back to cookies.

Step 3: Include the device ID in API requests

When your platform server sends a request to Airwallex, include the device ID in the x-risk-device-id header:

Shell

1curl -X POST Airwallex-Client-API-Endpoint \
2  -H 'x-risk-device-id: {device_id_from_user_browser_local_cache}' \
3  # ...other required headers and request body...

Most requests to Airwallex should be sent from your platform's server to keep the API key and secret secure. Never expose these credentials to the browser.

Web integration checklist

Load the device tracking script on every page.
Extract the device ID from the browser (localStorage or cookies).
Pass the device ID to your server and include it in the x-risk-device-id header for all Airwallex API requests.

iOS integration

For native iOS applications where end customers interact with your platform.

Step 1: Add the SDK dependency

Add the SDK using Swift Package Manager:

swift

1// Swift Package Manager
2dependencies: [
3    .package(url: "https://github.com/airwallex/airwallex-risk-ios", from: "1.0.0")
4]

Step 2: Initialize the SDK

Initialize the SDK when your app starts, typically in AppDelegate:

swift

1import AirwallexRisk
2
3@main
4class AppDelegate: UIResponder, UIApplicationDelegate {
5    func application(
6        _ application: UIApplication,
7        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
8    ) -> Bool {
9
10        // Initialize for Connected Accounts
11        Risk.start(
12            accountID: nil, // Will be set when end customer signs in
13            with: AirwallexRiskConfiguration(
14                isProduction: true, // true for production, false for demo
15                tenant: .scale
16            )
17        )
18
19        return true
20    }
21}

Set isProduction to true for production environments, false for demo or testing. Set tenant to .scale for the Connected Accounts scenario.

Step 3: Set the account ID when the end customer signs in

When your end customer signs in to your platform, set their Airwallex connected account ID:

swift

1// When end customer signs in
2let accountId = "acc_..." // From Airwallex Accounts API
3Risk.set(accountID: accountId)
4
5// When end customer signs out
6Risk.set(accountID: nil)

Step 4: Add the request header to API requests

When your app sends a request to Airwallex, include the device tracking header. You can use the Risk.header property:

swift

1import AirwallexRisk
2
3guard let header = Risk.header else {
4  return
5}
6var request = URLRequest(url: URL(string: "https://www.airwallex.com/...")!)
7request.setValue(header.value, forHTTPHeaderField: header.field)

Alternatively, use the convenience URLRequest extension:

swift

1import AirwallexRisk
2
3var request = URLRequest(url: URL(string: "https://www.airwallex.com/...")!)
4request.setAirwallexHeader()

The header field is always x-risk-device-id and the value is an internally generated device identifier.

iOS integration checklist

Initialize SDK on app launch with tenant: .scale.
Set the account ID when the end customer signs in.
Clear the account ID when the end customer signs out.
Include the device tracking header in all Airwallex API requests.

Android integration

For native Android applications where end customers interact with your platform.

Step 1: Add the SDK dependency

Add the SDK to your app's build.gradle:

Kotlin

1dependencies {
2    implementation "io.github.airwallex:RiskSdk:1.1.1"
3}

Step 2: Initialize the SDK

Initialize the SDK in your Application class:

Kotlin

1import com.airwallex.risk.AirwallexRisk
2import com.airwallex.risk.RiskConfiguration
3import com.airwallex.risk.Tenant
4
5class YourApplication : Application() {
6    override fun onCreate() {
7        super.onCreate()
8
9        // Initialize for Connected Accounts
10        AirwallexRisk.start(
11            applicationContext = applicationContext,
12            accountId = null, // Will be set when end customer signs in
13            configuration = RiskConfiguration(
14                isProduction = true, // true for production, false for demo
15                tenant = Tenant.SCALE
16            )
17        )
18    }
19}

Set isProduction to true for production environments, false for demo or testing. Set tenant to Tenant.SCALE for the Connected Accounts scenario.

Step 3: Set the account ID when the end customer signs in

When your end customer signs in to your platform, set their Airwallex connected account ID:

Kotlin

1// When end customer signs in
2val accountId = "acc_..." // From Airwallex Accounts API
3AirwallexRisk.setAccountId(accountId = accountId)
4
5// When end customer signs out
6AirwallexRisk.setAccountId(accountId = null)

Step 4: Add the request header to API requests

When your app sends a request to Airwallex, include the device tracking header. The implementation varies depending on your networking library (for example, Ktor or OkHttp ).

Kotlin

1import com.airwallex.risk.AirwallexRisk
2
3val header = AirwallexRisk.header
4
5// Add a header using header.field and header.value to airwallex.com network requests

The header field is always x-risk-device-id and the value is an internally generated device identifier.

Android integration checklist

Initialize SDK on app launch with tenant: Tenant.SCALE.
Set the account ID when the end customer signs in.
Clear the account ID when the end customer signs out.
Include the device tracking header in all Airwallex API requests.

Where to find the account ID

The account ID is returned when you create a connected account via the Airwallex API:

Shell

1POST https://api.airwallex.com/api/v1/accounts/create
2
3Response:
4{
5  "id": "acc_hkdm4fzf8_tz2yvw2cg", // Use this value
6  "legal_name": "End Customer Business Name",
7  ...
8}

Use the account ID from the Airwallex API (format: acc_...). Do not use userId — only use accountId. Use the connected account's ID, not your platform's internal user IDs.

Test your integration

Web

Verify the script loads successfully (check browser DevTools > Network tab).
Confirm AWX_RISK_ID exists in localStorage or cookies after page load.
Verify the device ID is passed from the browser to your server.
Confirm the x-risk-device-id header is included in Airwallex API calls.

Mobile (iOS and Android)

Verify SDK initializes on app launch without errors.
Confirm the tenant is set correctly (.scale for iOS, Tenant.SCALE for Android).
Verify the account ID is set when the end customer signs in.
Confirm the account ID is cleared when the end customer signs out.
Verify the device tracking header is included in Airwallex API requests.

Troubleshooting

Platform	Issue	Solution
Web	Device ID not found	Ensure the script has loaded. Check `localStorage` first, then cookies for `AWX_RISK_ID`.
Web	Script not loading	Check that your Content Security Policy (CSP) allows `static.airwallex.com`.
Mobile	SDK not initializing	Verify initialization in your `Application` or `AppDelegate`. Check ProGuard rules (Android).
Mobile	Account ID not working	Ensure you are using the account ID from the Airwallex API (starts with `acc_`), not internal user IDs.

Additional resources

Was this page helpful?