Airwallex Risk Android SDK

The Airwallex Risk SDK provides device intelligence and fraud detection capabilities for merchant and platform apps that integrate with Airwallex services.

Use Cases

This SDK supports two primary scenarios:

1. Payment Acceptance (PA): For merchant mobile apps accepting payments
2. Connected Accounts: For platforms that programmatically create connected accounts for businesses and individuals, and enable them with financial capabilities

Table of contents

• Requirements
• Installation
• Usage
  • Quick start
  • Update user
  • Events
  • Request header

Requirements

The Airwallex Risk Android SDK requires Android Studio Flamingo or later with Java 17 and is compatible with apps targeting Android 8 or above.

Installation

Gradle

In your app's build.gradle, add:

implementation "io.github.airwallex:RiskSdk:1.1.2"

Usage

Quick start

The SDK must be started as early as possible in your application lifecycle. We recommend calling the start method in your Application subclass's onCreate.

For Payment Acceptance (PA) scenario:

import android.app.Application
import com.airwallex.risk.AirwallexRisk
import com.airwallex.risk.RiskConfiguration
import com.airwallex.risk.Tenant

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        AirwallexRisk.start(
            applicationContext = applicationContext,
            accountId = "YOUR_MERCHANT_ACCOUNT_ID", // Required: The PA merchant's account ID at Airwallex
            configuration = RiskConfiguration(
                isProduction = !BuildConfig.DEBUG,
                tenant = Tenant.PA
            )
        )
    }
}

For Connected Accounts scenario:

import android.app.Application
import com.airwallex.risk.AirwallexRisk
import com.airwallex.risk.RiskConfiguration
import com.airwallex.risk.Tenant

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        AirwallexRisk.start(
            applicationContext = applicationContext,
            accountId = null, // Optional: Set connected account ID later via AirwallexRisk.setAccountId()
            configuration = RiskConfiguration(
                isProduction = !BuildConfig.DEBUG,
                tenant = Tenant.SCALE
            )
        )
    }
}

Notes:

• Payment Acceptance:
  • accountId is required and should be the PA merchant's account ID at Airwallex
  • tenant must be set to Tenant.PA
• Connected Accounts:
  • accountId is optional at startup (set it later via AirwallexRisk.setAccountId() once the platform user signs in and the connected account is available)
  • tenant must be set to Tenant.SCALE
• The optional RiskConfiguration may also be used if needed. For test/debug builds you can set isProduction = false.

Update user

The SDK needs to be updated when users sign in or out.

For Payment Acceptance (PA) scenario:

There are two cases for setting user ID:

Case 1: Registered user checkout (Recommended)

When using registered user checkout, set the user ID to the Airwallex Customer ID after creating the customer:

import com.airwallex.risk.AirwallexRisk

// After creating a customer at Airwallex via Create a Customer API
AirwallexRisk.setUserId(userId = "AIRWALLEX_CUSTOMER_ID") // Set to Airwallex Customer ID
AirwallexRisk.setUserId(userId = null) // Set to null on sign out

⚠️ Important: The user ID should be the Airwallex Customer ID returned from the Create a Customer API.

Case 2: Guest checkout

For guest checkout flows where users don't register, you can skip setting the user ID:

// No need to call AirwallexRisk.setUserId() for guest checkout

For Connected Accounts scenario:

Required: When a platform user (connected account) signs in or out, set only the account ID:

import com.airwallex.risk.AirwallexRisk

// On platform user sign in
val connectedAccountId = "CONNECTED_ACCOUNT_ID" // The connected account's Airwallex account ID from Create a connected account API
AirwallexRisk.setAccountId(accountId = connectedAccountId)

// On platform user sign out
AirwallexRisk.setAccountId(accountId = null)

⚠️ Important: For Connected Accounts, do NOT set userId. Only set accountId to the connected account's Airwallex account ID (not the platform's account ID). The account ID is the id returned from the Create a connected account API.

Events

Use the following snippet to send event name and current screen name.

import com.airwallex.risk.AirwallexRisk

// Log a custom event
AirwallexRisk.log(
  event = "EVENT_NAME",
  screen = "SCREEN_NAME"
)

// Log a predefined event
AirwallexRisk.log(
  event = AirwallexRisk.Events.TRANSACTION_INITIATED,
  screen = "checkout_screen"
)

// Available predefined events:
// - AirwallexRisk.Events.TRANSACTION_INITIATED
// - AirwallexRisk.Events.CARD_PIN_VIEWED
// - AirwallexRisk.Events.CARD_CVC_VIEWED
// - AirwallexRisk.Events.PROFILE_PHONE_UPDATED
// - AirwallexRisk.Events.PROFILE_EMAIL_UPDATED

Note

User login and logout events will be automatically logged when you call AirwallexRisk.setUserId()

Request header

When your app sends a request to Airwallex, you must add the provided header into your request before sending. This will be slightly different depending on your networking library, so check the documentation describing how to add headers for the library you're using.

Some networking libraries you may be using

• Ktor
• OkHttp

import com.airwallex.risk.AirwallexRisk

val header = AirwallexRisk.header

// Add a header using `header.field` and `header.value` to airwallex.com network requests

The header consists of

• the field, which will always be "x-risk-device-id", and
• the value, which will be an internally generated device identifier.