Skip to content

PaymentSheetConfiguration

Groups the credentials, environment flag, and optional 3D Secure configuration passed to CompletePaymentSheet. Previously these were top-level composable parameters; they've been moved into a dedicated class so future options can be added without widening the composable signature.

PaymentSheetConfiguration shape

data class PaymentSheetConfiguration(
    val applicationId: String,
    val environment: PaymentSheetEnvironment,
    val merchantId: String? = null,
    val apiUsername: String? = null,
    val apiPassword: String? = null,
    val threeDSConfiguration: ThreeDSConfiguration? = null,
)
PropertyTypeRequiredDescription
applicationIdStringYesYour Finix Application ID, found in the Finix Dashboard. Application IDs are environment-specific — use the one that matches environment.
environmentPaymentSheetEnvironmentYesThe Finix environment the SDK targets: PaymentSheetEnvironment.LIVE, PaymentSheetEnvironment.SANDBOX, or PaymentSheetEnvironment.QA.
merchantIdString?NoFinix Merchant ID. Required when threeDSConfiguration is set — the SDK forwards it to /3d_secure_sessions.
apiUsernameString?NoFinix API username used to authenticate the 3DS session call.
apiPasswordString?NoFinix API password used to authenticate the 3DS session call.
threeDSConfigurationThreeDSConfiguration?NoWhen set, runs 3D Secure authentication after tokenization. Omit (or pass null) to leave 3DS disabled. See ThreeDSConfiguration.
Do not embed production API credentials

apiUsername and apiPassword are privileged Finix API credentials — even ROLE_MERCHANT keys can create Transfers (see API Keys). Credentials embedded in a distributed APK can be extracted and reused by an attacker. For live mode, mint short-lived or scope-restricted credentials from your backend and inject them at runtime, or proxy the 3DS session call through your backend rather than shipping the live account key with the app.

PaymentSheetEnvironment

Selects which Finix environment the SDK targets. Pair the value with the matching applicationId and (when 3DS is enabled) the matching API credentials.

enum class PaymentSheetEnvironment {
    LIVE,
    SANDBOX,
    QA,
}

ThreeDSConfiguration

Enables 3D Secure (3DS) card authentication after tokenization. When set on PaymentSheetConfiguration, the SDK calls /3d_secure_sessions, presents a WebView challenge if required, and polls the session until it reaches a terminal state. The outcome is returned via PaymentSheetResponse.threeDSResponse.

If threeDSConfiguration is null, tokenization behaves exactly as before — existing integrations are unaffected.

ThreeDSConfiguration shape

data class ThreeDSConfiguration(
    val redirectScheme: String,
    val isEnabled: Boolean,
)
PropertyTypeRequiredDescription
redirectSchemeStringYesCustom URL scheme the issuer's challenge page returns to when authentication completes. Must match an intent-filter in your app's AndroidManifest.xml — see Register the redirect URL scheme.
isEnabledBooleanYesSet to false to construct a ThreeDSConfiguration without triggering 3DS. Useful for runtime toggles. Unlike the iOS counterpart, this parameter has no default — pass it explicitly.

Creating a ThreeDSConfiguration

The redirectScheme tells the SDK which URL to listen for when the issuer's challenge page redirects back to your app. Register the same scheme in your AndroidManifest.xml or the SDK will time out waiting for the redirect.

val threeDS = ThreeDSConfiguration(
    redirectScheme = "yourappscheme://redirect",
    isEnabled = true,
)

Full example

Compose a PaymentSheetConfiguration with 3D Secure enabled.

val configuration = PaymentSheetConfiguration(
    applicationId = "APgPDQrLD52TYvqazjHJJchM",
    environment = PaymentSheetEnvironment.LIVE,
    merchantId = "MUxxxxxxxx",
    apiUsername = "USxxxxxxxx",
    apiPassword = "your-api-password",
    threeDSConfiguration = threeDS,
)

val threeDS = ThreeDSConfiguration(
    redirectScheme = "yourappscheme://redirect",
    isEnabled = true,
)

val configuration = PaymentSheetConfiguration(
    applicationId = "APgPDQrLD52TYvqazjHJJchM",
    environment = PaymentSheetEnvironment.LIVE,
    merchantId = "MUxxxxxxxx",
    apiUsername = "USxxxxxxxx",
    apiPassword = "your-api-password",
    threeDSConfiguration = ThreeDSConfiguration(
        redirectScheme = "yourappscheme://redirect",
        isEnabled = true,
    ),
)