Upgrading your checkout experience

Migrate from legacy Spreedly iFrame or mobile WebView payment collection to Spreedly’s modern Checkout SDKs while keeping tokenization secure and preserving your existing backend transaction flow.

Use this guide as the main migration plan for existing iFrame customers. It covers the common architecture changes across Web, iOS, Android, and React Native, then gives detailed guidance for moving a browser-based iFrame integration to the Web Checkout SDK.

Review the tokenization guide to choose the Checkout SDK that matches each payment page.

Choose your migration path

For mobile migrations, use the platform-specific guides:

Implement SDK authentication

All of Spreedly's Checkout SDKs require server-generated authentication parameters for tokenization success. This is the most important architectural change for legacy iFrame integrations that relied only on a static Spreedly environment key.

Create a secure backend endpoint that your web page or mobile app calls before initializing the SDK.

1. Generate the auth parameters on your backend, not in browser JavaScript or mobile app code.
2. Create a unique nonce for each checkout session.
3. Issue a certificate_token.
4. Generate a UTC timestamp.
5. Create an HMAC signature using your Spreedly API secret.
6. Return the generated values to the client only for the active checkout attempt.

Full details on these authentication steps and required parameters are available in our payment page security guide.

Scenario A: Migrating web iFrame pages to the Web Checkout SDK

Use this section if your current checkout page loads the legacy Spreedly iFrame or Express JavaScript directly in a browser.

1. Remove legacy browser code

Remove the legacy Spreedly JavaScript references and the code that depends on them.

1. Remove old v1 iFrame script references.
2. Remove old v2 or v3 Express script references.
3. Remove legacy iFrame setup code, including old field creation, style, and lifecycle calls.
4. Remove tokenization calls that depend on the legacy global iFrame or Express objects.
5. Keep your existing backend transaction endpoints for purchase, authorize, vaulting, or receiver delivery if they already process Spreedly payment method tokens.

The Checkout SDK still returns a payment method token. In nearly all cases, your server-side transaction flow can continue to use that token the same way it did after legacy iFrame tokenization.

2. Add the new Web SDK script

Load the Web Checkout SDK from the Spreedly CDN. Use Subresource Integrity (SRI) hashes so the browser can verify that the downloaded file has not been modified.

Choose the script that matches your target checkout experience:

Use Hosted Fields when you want to control the surrounding checkout layout and mount secure Spreedly fields into specific containers. Use Express Checkout when you want Spreedly to render the checkout form inline or as a modal.

3. Fetch auth parameters before SDK initialization

Before creating the Web SDK instance, call your backend authentication endpoint from the checkout page.

1. Request fresh auth parameters from your backend endpoint, such as /api/v1/auth/params.
2. Confirm the response includes the required secure parameters for the checkout session.
3. Pass the returned auth details into the SDK constructor.

For Hosted Fields, initialize the SDK with new SpreedlyHostedFields(authDetails). For Express Checkout, initialize the SDK with new SpreedlyExpressCheckout(authDetails).

4a. Replace legacy iFrame fields with Hosted Fields

Use Hosted Fields when you want the new integration to resemble your existing iFrame checkout page.

1. Add empty container elements for sensitive card fields, such as card number and CVV.
2. Keep non-sensitive fields, such as cardholder name or billing address, in your own page markup when appropriate.
3. Call inAppElements() to mount Spreedly-managed secure fields into the containers.
4. Move validation and submission logic to the Web SDK lifecycle instead of the legacy iFrame lifecycle.
5. Listen for the tokenGenerated event and extract the token from the success payload.

Do not collect raw PAN or CVV values in your own JavaScript. Sensitive card details should be entered only through Spreedly-managed secure fields.

4b. Replace legacy Express with Web SDK Express Checkout

Use Express Checkout when you want Spreedly to render the payment form for the customer.

1. Initialize new SpreedlyExpressCheckout(authDetails) with fresh backend-generated auth parameters.
2. Call expressCheckout() to present the form.
3. Pass a parentContainerId when you want to embed the form inline.
4. Omit parentContainerId when you want the form to open as a modal dialog.
5. Listen for the tokenGenerated event and send the resulting token to your backend.

This path is the closest replacement for legacy Express integrations where Spreedly continues to own the rendered payment form.

5. Update Content Security Policy headers

Update your Content Security Policy (CSP) so the new SDK scripts and secure frames can load correctly.

1. Allow the new Spreedly CDN and frame domains required by the Web Checkout SDK.
2. Remove legacy allowances that were used only by the old iFrame or Express scripts.
3. Apply strict frame-ancestors directives to prevent clickjacking.
4. Test the page in report-only mode first if your production CSP is strict.

6. Verify the Web SDK migration

Before releasing the migrated checkout page, confirm that:

• No legacy iFrame or Express script references remain.
• The page fetches SDK auth parameters from your backend before SDK initialization.
• Your Spreedly API secret is not present in client-side code.
• Card number and CVV are entered only through Spreedly-managed secure fields or forms.
• The tokenGenerated event fires on successful tokenization.
• The token is sent immediately to your backend for purchase, authorize, vaulting, or another transaction flow.
• Your CSP allows the new SDK and blocks unexpected framing.
• Existing error and retry states still show clear messages to the customer.

Scenario B: Migrating mobile WebViews to native Checkout SDKs

If your Android, iOS, or React Native app currently loads the Spreedly iFrame or Express inside a WebView, replace that WebView flow with the native Checkout SDK for the platform.

Native Checkout SDKs remove the need for JavaScript bridges and WebView payment pages. They also keep sensitive payment data inside SDK-owned secure UI components.

Android summary

For Android, remove WebView payment code such as WebView, WebSettings, setJavaScriptEnabled, @JavascriptInterface, addJavascriptInterface, Spreedly JavaScript references, and evaluateJavascript tokenization calls.

Install the Android Checkout SDK modules you need, such as checkout-payments-core, checkout-hostedfields, and checkout-paymentsheet. Use SPLTextField composables for custom payment forms or launch the Android payment sheet for Express Checkout. Collect results from sdk.paymentResultFlow and subscribe before starting tokenization so you do not miss emissions.

Follow Migrate from iFrame to the Android Checkout SDK for the full Android migration checklist.

iOS summary

For iOS, replace webview-based payment collection with the iOS Checkout SDK. Install the modular SDK packages needed for your checkout, such as SpreedlyCore, SpreedlySecurity, and SpreedlyUI.

Use native secure fields for custom forms or CardFormDropIn for drop-in checkout. Initialize the SDK with backend-generated authentication parameters and send successful tokens to your backend immediately.

Follow Migrate from iFrame to the iOS Checkout SDK for the full iOS migration checklist.

React Native summary

For React Native, replace WebView-based payment collection with @spreedly/react-native-checkout. Use the native SDK components instead of standard text inputs for sensitive payment fields.

Fetch fresh auth parameters from your backend before SDK initialization. Do not store payment tokens in insecure local storage such as AsyncStorage, UserDefaults, or SharedPreferences.

Follow Migrate from iFrame to the React Native Checkout SDK for the full React Native migration checklist.

Handling the token lifecycle

Across Web and native SDKs, the migration goal is the same: collect payment details through SDK-owned secure UI, receive a Spreedly payment method token, and send that token to the backend for processing.

1. Listen for the platform-specific completion event:
   • Web: tokenGenerated
   • iOS: PaymentResult publisher
   • Android: paymentResultFlow
   • React Native: SpreedlyEventEmitter
2. Extract the payment method token only after a success result.
3. Send the token immediately to your backend.
4. Use the token in your existing backend purchase, authorize, vaulting, or receiver flow.
5. Remove the token from client-side memory after handoff.

Migration checklist

Use this checklist before launching any migrated checkout flow.

• Backend-generated SDK authentication is implemented.
• No Spreedly API secret is present in browser or mobile app code.
• Legacy iFrame, Express, WebView, or JavaScript bridge code has been removed from migrated flows.
• Sensitive payment fields are collected only by Spreedly-managed secure fields or drop-in forms.
• Success, failure, cancellation, and validation states are handled explicitly.
• Tokens are sent to your backend immediately and are not stored in local client storage.
• Your existing backend transaction flow accepts tokens from the new SDK.
• Test transactions complete successfully in a non-production environment.