Migrate from iFrame to the Android Checkout SDK

Move from the legacy mobile-sdk-android or a WebView-based iFrame/Express integration to the modern Checkout Android SDK.

Use this guide when your Android app currently loads Spreedly iFrame UI or a web checkout inside a webview. Match outcomes such as tokenization, validation, field-state handling, and PCI boundaries instead of trying to recreate identical JavaScript method names.

Start with Upgrading your checkout experience if you need the cross-platform migration plan or the detailed Web iFrame to Web Checkout SDK migration path.

This guide covers two migration paths:

• Path A -- From the old native mobile-sdk-android (com.spreedly:client, com.spreedly:express, com.spreedly:securewidgets)
• Path B -- From Spreedly iFrame or Express running inside an Android WebView

Both paths converge on the same modern SDK. If you are already on the Checkout Android SDK and upgrading between versions, see the version-specific migration guides instead.

Further reading

• Review the legacy iFrame UI and iFrame events references when mapping old browser behavior.
• Review Tokenization to choose the correct SDK flow for each payment page.

What you gain

The Checkout Android SDK replaces both the old native SDK and WebView-based approaches with:

• Jetpack Compose UI with full theming and dark mode support
• Server-side authentication (no secrets on-device)
• PCI scope reduction (sensitive data never touches merchant code)
• ACH bank account tokenization
• 3D Secure authentication (Forter global and gateway-specific)
• Alternative payment methods (Stripe APM, Braintree APM)
• Offsite payments (PayPal, Pix, Boleto, OXXO, NuPay)
• CVV recaching for saved cards
• Screen capture protection (FLAG_SECURE)
• Built-in telemetry via Datadog

Compatibility

See the README compatibility table for minimum and recommended versions of Android API, Kotlin, AGP, KSP, Gradle, and Android Studio.

Architectural differences

Step 1: Implement server-side authentication

This is the biggest change in both paths. The old SDK stored your API secret directly in the app. The new SDK requires a server endpoint that generates signed authentication parameters for each checkout session.

Old SDK (Path A)

SpreedlyClient client = SpreedlyClient.newInstance("envKey", "envSecret", true);

WebView (Path B)

Auth was either embedded in the iFrame configuration or passed through addJavascriptInterface.

New SDK (both paths)

Your backend generates signed params per session. The app fetches them and passes them to the SDK:

val sdk = Spreedly()
sdk.init(
    SpreedlySDKInitOptions(
        nonce = authParams.nonce,
        signature = authParams.signature,
        certificateToken = authParams.certificateToken,
        timestamp = authParams.timestamp,
        environmentKey = "your_environment_key",
        context = applicationContext,
    ),
)

Backend endpoint (pseudocode)

Your server needs an endpoint that generates these parameters. At a high level:

POST /api/v1/auth/params

1. Generate a unique nonce (UUID or similar)
2. Get the current UTC timestamp
3. Retrieve your certificate_token from Spreedly
4. Create an HMAC-SHA256 signature using your Spreedly API secret:
     signature = HMAC-SHA256(secret, nonce + timestamp + certificate_token)
5. Return JSON: { nonce, signature, certificate_token, timestamp }

Never generate these values in client-side code. The API secret must stay on your server.

Step 2: Remove old dependencies

Path A -- Old native SDK

Remove the old Maven repository and artifacts from your Gradle files:

 // settings.gradle(.kts) or build.gradle(.kts)
 repositories {
-    maven { url = uri('https://raw.githubusercontent.com/spreedly/mobile-sdk-android/maven/') }
 }

 // app/build.gradle(.kts)
 dependencies {
-    implementation 'com.spreedly:client:0.1-beta'
-    implementation 'com.spreedly:express:0.1-beta'
-    implementation 'com.spreedly:securewidgets:0.1-beta'
 }

If RxJava was only used for the Spreedly SDK, remove those dependencies too:

-    implementation 'io.reactivex.rxjava2:rxjava:2.x.x'
-    implementation 'io.reactivex.rxjava2:rxandroid:2.x.x'

Path B -- WebView integration

Remove all WebView-based payment code:

• The WebView component and its configuration (WebSettings, setJavaScriptEnabled)
• Any @JavascriptInterface bridge class used to communicate with the iFrame/Express form
• addJavascriptInterface calls
• The iFrame or Express <script> tag references (spreedly.js, express-checkout.js)
• CSP or WebViewClient overrides related to Spreedly domains
• JavaScript evaluation calls (evaluateJavascript) for tokenization

Step 3: Add new SDK dependencies

Add the Spreedly Maven repository (GitHub Packages) and the SDK artifacts:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/spreedly/checkout-android-maven")
            credentials {
                username = "your_github_username"
                password = "your_github_personal_access_token" // needs read:packages scope
            }
        }
        // When using checkout-threeds (Global or Gateway-Specific 3DS):
        // maven {
        //     url = uri("https://mobile-sdks.forter.com/android")
        //     credentials { ... }  // see ../3ds-global.md#step-1-add-maven-repository
        // }
        google()
        mavenCentral()
    }
}

// app/build.gradle.kts
dependencies {
    // Typical card UI (payments-core is always required)
    implementation("com.spreedly:checkout-payments-core:$spreedlyVersion")
    implementation("com.spreedly:checkout-hostedfields:$spreedlyVersion")   // SPLTextField / custom forms
    implementation("com.spreedly:checkout-paymentsheet:$spreedlyVersion")   // pre-built bottom sheet

    // 3DS — uncomment when using Global or Gateway-Specific 3DS
    // implementation("com.spreedly:checkout-threeds:$spreedlyVersion")

    // Optional — add only the flows you use
    // implementation("com.spreedly:checkout-braintree-apm:$spreedlyVersion")  // PayPal, Venmo
    // implementation("com.spreedly:checkout-stripe-apm:$spreedlyVersion")     // iDEAL, Bancontact, EPS, P24, SEPA
    // implementation("com.spreedly:checkout-stripe-radar:$spreedlyVersion")   // Stripe Radar fraud sessions
}

See the README installation notes for when each module and repository is required.

ProGuard / R8

If you use custom ProGuard rules, add:

-keep class com.spreedly.** { *; }
-keepclassmembers class com.spreedly.** { *; }
-keep class io.ktor.** { *; }

Step 4: Migrate payment flows

Key architectural change: no raw card data in merchant code

The old SDK let merchant code construct CreditCardInfo objects containing raw card numbers and CVVs. The new SDK does not have an equivalent. All sensitive data flows through SDK-owned secure components:

• SPLTextField composables write card data to internal encrypted state
• sdk.callbacks methods update internal PaymentSheetState

The createCreditCard() and createPaymentMethod() methods read from that internal state. Your code never handles raw card numbers, CVVs, or account numbers directly. This is a PCI scope reduction by design.

Option A: Express Checkout (pre-built bottom sheet)

The fastest migration path. Replaces ExpressBuilder (old SDK) or the Express JS form (WebView) with a pre-built Compose bottom sheet.

Kotlin (Compose)

// 1. Initialize
val sdk = Spreedly()
sdk.init(initOptions)

// 2. Place the bottom sheet in your Compose tree
@Composable
fun CheckoutScreen() {
    SpreedlyBottomSheet(sdk = sdk)
}

// 3. Collect results BEFORE triggering the sheet
lifecycleScope.launch {
    sdk.paymentResultFlow.collect { result ->
        when (result) {
            is PaymentResult.Completed -> {
                val token = result.token
                // Send token to your backend
            }
            is PaymentResult.Failed -> {
                val error = result.getDescription()
                // Show error to user
            }
            is PaymentResult.Canceled -> {
                // User dismissed the sheet
            }
            PaymentResult.Initial -> { /* Waiting */ }
        }
    }
}

// 4. Show the sheet
sdk.expressCheckout()

SpreedlyBottomSheet accepts parameters for customization: nameFieldDisplayMode, yearFormat, additionalFields, showSavePaymentCheckbox, savePaymentCheckboxLabel, allowBlankName, allowBlankDate, allowExpiredDate, and config: PaymentSheetConfig for color overrides.

See the Express Checkout guide for the full parameter reference.

Java (using PaymentSheetJavaHelper)

If you are not ready to adopt Kotlin, use PaymentSheetJavaHelper to mount the bottom sheet inside a ComposeView from a traditional Activity or Fragment:

// In your Activity's onCreate or Fragment's onCreateView
ComposeView composeView = findViewById(R.id.compose_view);
PaymentSheetJavaHelper.setupContent(composeView, sdk);

// Observe results
PaymentSheetJavaHelper.observePaymentResults(sdk, lifecycleOwner, result -> {
    if (result instanceof PaymentResult.Completed) {
        String token = ((PaymentResult.Completed) result).getToken();
        // Send token to your backend
    }
});

// Show the sheet
sdk.expressCheckout();

What maps to what

Option B: Custom payment forms (hosted fields)

Build your own payment form layout using secure SPLTextField composables for sensitive fields and standard Compose components for everything else.

Old SDK mapping

Kotlin example

@Composable
fun CustomPaymentForm(sdk: Spreedly) {
    val coroutineScope = rememberCoroutineScope()
    var cardValue by remember { mutableStateOf("") }
    var expiryValue by remember { mutableStateOf("") }
    var cvvValue by remember { mutableStateOf("") }

    Column {
        SPLTextField(
            formFieldType = FormFieldType.CARD(true),
            sdk = sdk,
            label = "Card Number",
            value = cardValue,
            onChange = { cardValue = it },
        )
        SPLTextField(
            formFieldType = FormFieldType.EXPIRY_DATE(true),
            label = "Expiry Date (MM/YY)",
            value = expiryValue,
            onChange = { expiryValue = it },
        )
        SPLTextField(
            formFieldType = FormFieldType.CVV(true),
            sdk = sdk,
            label = "CVV",
            value = cvvValue,
            onChange = { cvvValue = it },
        )

        Button(onClick = {
            coroutineScope.launch {
                val result = sdk.createCreditCard(
                    formFields = listOf(
                        FormFieldType.CARD(true),
                        FormFieldType.EXPIRY_DATE(true),
                        FormFieldType.CVV(true),
                    ),
                    additionalFields = mapOf(
                        AdditionalField.FULL_NAME to "Jane Doe",
                    ),
                )
                when (result) {
                    is PaymentProcessingResult.Processing -> {
                        // Validation passed, request sent.
                        // Final result arrives on sdk.paymentResultFlow.
                    }
                    is PaymentProcessingResult.ValidationFailed -> {
                        // result.invalidFields lists which fields failed
                    }
                }
            }
        }) {
            Text("Pay")
        }
    }
}

Java callers: Use HostedFieldsJavaHelper to mount a default card form inside a ComposeView.

See the Custom Payment Forms guide for the full field reference, validation patterns, and bank account fields.

Understanding the "no raw card data" change

If you used the old SDK's headless SpreedlyClient API, you may have constructed card data directly:

// OLD SDK -- merchant code touches raw card data
CreditCardInfo info = new CreditCardInfo(
    "Full Name",
    new SpreedlySecureOpaqueString("4111111111111111"),
    new SpreedlySecureOpaqueString("432"),
    2025, 12
);
client.createCreditCardPaymentMethod(info, null, null).subscribe(...);

The new SDK has no equivalent to this pattern. Card data must flow through SPLTextField composables or sdk.callbacks, which populate internal encrypted state. You then call sdk.createCreditCard() or sdk.createPaymentMethod() to trigger tokenization from that internal state.

For the lower-level createPaymentMethod() overload (returns Result<PaymentMethodResponse, SpreedlyNetworkError> directly), card state must still have been populated via callbacks or SPL fields first.

Step 5: Migrate result handling

All integration tiers (express, custom, headless) deliver results through the same SharedFlow.

Old SDK (Express) -- onActivityResult

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == 1000 && resultCode == Activity.RESULT_OK) {
        String token = data.getStringExtra(ExpressBuilder.EXTRA_PAYMENT_METHOD_TOKEN);
        // Send token to backend
    }
}

Old SDK (headless) -- RxJava subscribe()

client.createCreditCardPaymentMethod(info, null, null)
    .subscribe(new SingleObserver<TransactionResult<PaymentMethodResult>>() {
        @Override
        public void onSubscribe(Disposable d) {}

        @Override
        public void onSuccess(TransactionResult<PaymentMethodResult> trans) {
            if (trans.succeeded) {
                String token = trans.result.token;
                // Send token to backend
            } else {
                String error = trans.message;
                // Handle error
            }
        }

        @Override
        public void onError(Throwable e) {
            // Network or unexpected error
        }
    });

New SDK -- paymentResultFlow

lifecycleScope.launch {
    sdk.paymentResultFlow.collect { result ->
        when (result) {
            is PaymentResult.Completed -> {
                val token = result.token
                // Send token to your backend to complete the transaction
            }
            is PaymentResult.Failed -> {
                handleError(result)
            }
            is PaymentResult.Canceled -> {
                // User dismissed the payment sheet
            }
            PaymentResult.Initial -> {
                // Waiting for payment
            }
        }
    }
}

Subscribe to paymentResultFlow before calling sdk.expressCheckout() or sdk.createCreditCard() to avoid missing emissions.

Step 6: Migrate error handling

Old SDK

if (trans.succeeded) {
    // success
} else {
    String errorMessage = trans.message;
    // single error string, no categorization
}

New SDK

PaymentResult.Failed provides structured error information:

is PaymentResult.Failed -> {
    when (result.errorType) {
        PaymentResult.Failed.ErrorType.API_ERROR -> {
            // Specific API error with categorization
            when (result.apiError) {
                SpreedlyApiError.VALIDATION_ERROR -> {
                    // Field-level validation errors available
                    result.validationErrors.forEach { error ->
                        // error.fieldName, error.errorMessage
                    }
                }
                SpreedlyApiError.ACCOUNT_INACTIVE -> { /* Test env with real card */ }
                SpreedlyApiError.UNAUTHORIZED -> { /* Auth issue */ }
                SpreedlyApiError.RATE_LIMITED -> { /* Back off and retry */ }
                else -> { /* result.getDescription() for user message */ }
            }
        }
        PaymentResult.Failed.ErrorType.NETWORK_ERROR -> {
            // Connection, timeout, IO errors
        }
        PaymentResult.Failed.ErrorType.UNKNOWN_ERROR -> {
            // Unexpected -- result.originalError has the Throwable
        }
    }
}

Key properties on PaymentResult.Failed:

• errorType -- API_ERROR, NETWORK_ERROR, or UNKNOWN_ERROR
• apiError: SpreedlyApiError? -- categorized API error type
• validationErrors: List<ValidationError> -- field-level errors with fieldName, errorKey, errorMessage
• message: String? -- primary error message
• statusCode: Int? -- HTTP status code
• getDescription() -- user-friendly error string
• hasValidationErrors() -- whether field-level errors are present
• getValidationErrors(fieldName) -- errors for a specific field

For recache results (Result<PaymentMethodResponse, SpreedlyNetworkError>), use SpreedlyErrorMessages.getUserFriendlyMessage(error) to get a display-ready string.

See the Error Handling guide for the full list of SpreedlyApiError values, field-specific error mapping, retry logic, and user-friendly message patterns.

Java interop

The old SDK was Java. The new SDK is Kotlin-first with Jetpack Compose; most payment modules provide a Java helper class (stripe-radar uses the SpreedlyStripeRadar Kotlin API instead):

These helpers bridge between Java Activities/Fragments and the Compose-based SDK. You still need to add ComposeView elements to your XML layouts. Over time, migrating to Kotlin and Compose directly is recommended for the best experience.

New capabilities

The Checkout SDK includes features not available in the old SDK or WebView approach:

For gateway-specific 3DS timing, Braintree behavior, and /complete handling, see 3DS Gateway-Specific.

Concept mapping reference

Quick-reference table for translating between old and new APIs.

Path A: Old native SDK to Checkout SDK

Path B: WebView to Checkout SDK

Public API inventory (merchant-facing)

Complete checklist of SDK APIs available to merchants. Use this to confirm you've wired everything your integration needs.

SDK-level (Spreedly instance)

ValidationParameter values

Headless SPLTextField (Compose)

HostedFieldState properties (on onFieldStateChange)

Express Checkout (SpreedlyBottomSheet / PaymentSheet)

Not available on Express (use headless SPLTextField if needed):

• onFieldStateChange per-field callbacks
• Custom trailingIcon on CARD
• Per-field onFocusChanged
• Granular onInputLength / digit counts during typing

EmailValidator

Legacy iFrame (JavaScript) 1:1 mapping

If you integrated Spreedly iFrame v1 (iframe-v1.min.js) inside a WebView or a mobile browser, use this table to find the Checkout Android pattern. Official legacy references: iFrame UI, iFrame events.

Status in the third column:

• Parity — Supported with an Android-first API or pattern.
• Platform — Same outcome via Android/Compose idioms (not a JS-shaped API).
• Gap — No equivalent today; read Notes for what to do instead.
• N/A — Web-only or not meaningful on Android.

Card-brand display during typing

Legacy fieldEvent / inputProperties.cardType let merchants swap icons and drive BIN UX while typing.

Android today

• Use SPLTextField.onFieldStateChange with com.spreedly.hostedfields.models.HostedFieldState — cardScheme is populated for FormFieldType.CARD on INPUT, VALIDATION, and focus-related events (typed CardScheme; map to your drawable assets).
• HostedFieldState.iin — merchant-safe issuer prefix (6 or 8 digits per scheme; null when fewer than six digits on the card field). Use for BIN-level UX while typing; it is omitted from HostedFieldState.toString() for logging safety.
• The SDK does not ship drawable assets for brands. By default, CardScheme.name is shown as Text in the trailing slot when the scheme is known. To replace that with an icon, pass trailingIcon = { scheme -> … } on SPLTextField (CARD fields only; null keeps the default text).
• CardNumberContext exists for internal CVV-length coupling and is not a supported merchant subscription API (payments-core/.../CardNumberContext.kt).

Safe field-state observability

HostedFieldState — Kotlin samples (Compose)

Merchant-owned icons (legacy iframe used cardType metadata; same pattern on Android):

var cardBrandIcon by remember { mutableStateOf<CardScheme?>(null) }

SPLTextField(
    formFieldType = FormFieldType.CARD(true),
    sdk = sdk,
    value = cardNumber,
    onChange = { cardNumber = it },
    onFieldStateChange = { state ->
        if (state.fieldType is FormFieldType.CARD) {
            cardBrandIcon = state.cardScheme
        }
    },
)
// Map cardBrandIcon to painterResource(R.drawable.ic_visa) etc. — do not log state if it could
// ever include sensitive fields; HostedFieldState is PAN-safe by design.

Safe length gating (do not parse ciphertext from onChange):

var digitCount by remember { mutableStateOf(0) }

SPLTextField(
    formFieldType = FormFieldType.CARD(true),
    sdk = sdk,
    value = cardNumber,
    onChange = { cardNumber = it },
    onFieldStateChange = { state ->
        state.numberLength?.let { digitCount = it }
    },
)

Pre-submit block using HostedFieldState.isValid (mirrors onValidationChange; use either or both):

var hostedCardValid by remember { mutableStateOf(false) }

SPLTextField(
    formFieldType = FormFieldType.CARD(true),
    sdk = sdk,
    value = cardNumber,
    onChange = { cardNumber = it },
    onFieldStateChange = { state ->
        if (state.eventType == HostedFieldEventType.VALIDATION ||
            state.eventType == HostedFieldEventType.INPUT
        ) {
            hostedCardValid = state.isValid
        }
    },
)
// Gate checkout: if (!hostedCardValid || sdk.hasValidationError(...)) return

Java — use non-null listener overloads so overload resolution is unambiguous (setupContent(composeView, sdk, listener) or setupContent(composeView, sdk, config, listener)):

HostedFieldsJavaHelper.setupContent(composeView, sdk, state -> {
    CardScheme scheme = state.getCardScheme();
    Integer len = state.getNumberLength();
    // Drive UI from getters; do not log raw payment data.
});

External mask toggle (iframe / iOS pattern)

The iframe has no eye icon inside the number or CVV iframes. Mask/reveal is merchant-owned UI outside the fields, calling Spreedly.setNumberFormat(...) or Spreedly.toggleMask() on the main thread. The Spreedly example app uses this pattern (not the in-field SDK toggle).

PRETTY is not iframe prettyFormat. On the web, prettyFormat keeps grouped digits visible when the field loses focus. On Android, CardNumberFormat.PRETTY applies blur masking (last-four style) when unfocused while panMasked is true. For digits that stay visible like iframe prettyFormat, use CardNumberFormat.PLAIN. For full bullets on every digit, use MASKED or toggleMask().

Multiple CARD fields: One Spreedly.hostedCardDisplayState applies to the whole SDK instance. Every CARD and CVV SPLTextField that receives the same sdk instance shares that snapshot (mask/format), unlike separate iframes with per-embed state.

Internal: SpreedlyUIController.setHostedCardDisplayState is SDK-internal and unused by merchant UIs — use Spreedly.setNumberFormat / toggleMask and collect hostedCardDisplayState instead.

Required wiring — pass the same sdk on CARD and CVV fields (display follows sdk.hostedCardDisplayState automatically):

SPLTextField(
    formFieldType = FormFieldType.CARD(true),
    sdk = sdk,
    label = "Card Number",
    value = cardNumber,
    onChange = { cardNumber = it },
)

SPLTextField(
    formFieldType = FormFieldType.CVV(true),
    sdk = sdk,
    label = "CVV",
    value = cvv,
    onChange = { cvv = it },
)

// Merchant UI: all three iframe formats (see sample app MerchantMaskToggleBar)
sdk.setNumberFormat(CardNumberFormat.PRETTY)   // prettyFormat — grouped digits
sdk.setNumberFormat(CardNumberFormat.PLAIN)    // plainFormat — reveal PAN + CVV
sdk.setNumberFormat(CardNumberFormat.MASKED)   // maskedFormat — full * on every digit

// iframe toggleMask() — coupled PAN + CVV; from PRETTY, first call → MASKED; second → PLAIN
Button(onClick = { sdk.toggleMask() }) { Text("toggleMask()") }

Java HostedFieldState: positional constructor includes isPanMasked as the 9th parameter; handle PAN_MASK_CHANGED in switch statements.

SPLTextField.forceMaskOnLifecycleStop (default true) — Android lifecycle overlay on ON_STOP when PAN was revealed; does not replace toggleMask() / controller state. See CHANGELOG.

Initialization and configuration

Validation and field state

Tokenization, reset, and listeners

Recache, errors, 3DS, telemetry

Release notes and docs

Verification checklist

• Build succeeds: ./gradlew assembleRelease
• No old dependency references: search for com.spreedly:client, com.spreedly:express, com.spreedly:securewidgets -- zero results
• No old Maven repo: search for raw.githubusercontent.com/spreedly/mobile-sdk-android -- zero results
• No WebView payment code remaining (Path B): search for addJavascriptInterface and spreedly in WebView-related files -- zero results
• No SpreedlyClient references: search for SpreedlyClient -- zero results
• No CreditCardInfo or SpreedlySecureOpaqueString references -- zero results
• Auth params fetched from backend, not hardcoded: no API secret in app code
• ProGuard/R8 rules added (if using custom ProGuard config)
• End-to-end payment flow works with test card 4111111111111111
• Token received and processed on backend

Getting help

• Testing Guide -- Test cards, environment setup, flow-by-flow procedures
• Troubleshooting -- Symptom-based debugging across all payment flows
• Getting Started -- Full setup walkthrough for new integrations
• Spreedly Support -- Open a ticket if you need migration assistance