Skip to content

Tokenize with Payment Sheet Android SDK

The Finix Android SDK lets you securely collect card and bank account details in your Android app using pre-built Jetpack Compose payment forms. Payment data is tokenized before it reaches your application, keeping sensitive card data out of your code and ensuring PCI compliance.

Tokens are created in Finix's vault and returned to your app. Use the token immediately to create a Payment Instrument via the Finix API.

Token Expiration

Tokens expire 30 minutes after creation. Create a Payment Instrument as soon as you receive the token.

Installing the library

The library is available on Maven Central. Add it to your build.gradle:

buildscript {
    ext.finix_version = '0.4.6'
}

dependencies {
    implementation "com.finix:finix-android-payment-sheet:$finix_version"
}

Your project must be configured for Jetpack Compose:

android {
    compileSdk 36
    defaultConfig {
        minSdk 24
        targetSdk 36
    }
    kotlinOptions {
        jvmTarget = 11
    }
    buildFeatures {
        compose true
    }
    composeOptions {
        kotlinCompilerExtensionVersion '1.5.15'
    }
}

System requirements

RequirementValue
minSdk24
targetSdk36
compileSdk36
Kotlin2.3.0
Kotlin Compiler Extension1.5.15
Material31.4.0
JVM target11
Kotlin Compatibility

Consult the Compose to Kotlin Compatibility Map if you need to match a specific Kotlin version.

Register the redirect URL scheme

Only required when you plan to enable 3D Secure. The issuer's challenge page redirects back to your app using a custom URL scheme — register the scheme you'll pass as ThreeDSConfiguration.redirectScheme in your AndroidManifest.xml so Android routes the redirect to the SDK.

<activity android:name=".CheckoutActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="yourappscheme" android:host="redirect" />
    </intent-filter>
</activity>

If the scheme is missing or doesn't match redirectScheme, the challenge window stays open until the SDK's 5-minute timeout fires onFailure with FinixErrorCode.ThreeDSFailed(AUTHENTICATION_TIMED_OUT).

Quick start

Render a payment sheet, handle the response, and dismiss the sheet on any terminal callback.

@Composable
fun CheckoutScreen() {
    val viewModel = viewModel<CheckOutViewModel>()
    val state = viewModel.state

    if (state.showPaymentSheet) {
        CompletePaymentSheet(
            configuration = PaymentSheetConfiguration(
                applicationId = "YOUR_APPLICATION_ID",
                environment = PaymentSheetEnvironment.SANDBOX, // use PaymentSheetEnvironment.LIVE for production
                merchantId = null,
                apiUsername = null,
                apiPassword = null,
                threeDSConfiguration = null, // see /android/online/configuration#threedsconfiguration to enable
            ),
            amount = amountInCents,
            currency = "USD",
            onCancel = { viewModel.setShowPaymentSheet(false) },
            onSuccess = { response ->
                // response.tokenizedResponse.id — use this to create a Payment Instrument via the Finix API
                viewModel.saveTokenResponse(response.tokenizedResponse)
                viewModel.setShowPaymentSheet(false)
            },
            onFailure = { error ->
                viewModel.showError(error)
                viewModel.setShowPaymentSheet(false)
            },
        )
    }
}

To enable 3D Secure, pass a ThreeDSConfiguration on PaymentSheetConfiguration and inspect response.threeDSResponse inside onSuccess — see PaymentSheetResponse.

API migration

The onDismiss / onTokenized signature shown in previous versions of this SDK is deprecated. See PaymentSheet » Deprecated signature for migration notes.