Migrate from iFrame to the iOS Checkout SDK

Replace an iOS webview-based Spreedly iFrame checkout with native SPLTextField fields or the CardFormDropIn pre-built card form while preserving your backend transaction flow.

Use this guide when your iOS 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.

Match outcomes (tokenize, validation, PCI boundaries), not 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.

Further reading

• Review the Checkout iOS SDK package repository for Swift Package Manager, CocoaPods, compatibility, and release details.
• 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.

Who this guide is for

Official legacy references: iFrame UI, iFrame events.

Start here

Five steps to replace iframe hosted fields on iOS:

1. App launch — Spreedly.initializeSDK() once. See Basic setup.
2. Before checkout — your server returns signed credentials; call Spreedly.setup(config:) (Swift) or setupWithConfig(_:) (Objective-C).
3. Choose UI — CardFormDropIn (fastest) or headless SPLTextField (iframe-style per-field callbacks). See Choose your path.
4. Tokenize — Spreedly.shared().createCreditCard(...) and listen on subscribeToPaymentResults (Swift) or paymentDelegate (ObjC). There is no createPaymentMethod on iOS.
5. Leave checkout — Spreedly.shared().reset() (alias resetPaymentState()). There is no destroy() — the SDK singleton stays alive. See SDK lifecycle.

Gate checkout on Spreedly.isInitialized. Setup and lifecycle details: getting-started.md.

Quick legacy → iOS cheat sheet

Choose your path: headless vs express

Rule of thumb: iframe merchants who relied on fieldEvent per keystroke → headless. Merchants who only need a working card form → express.

Deep dives: Custom Payment Forms (headless), Express Checkout (drop-in).

Not the same as iframe

Read this before coding — intentional differences from iframe v1 (by design, not missing card features).

Status (in the Status column of mapping tables below):

• Parity — Supported with an iOS-first API or pattern.
• Platform — Same outcome via iOS/UIKit 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 iOS.

iframe inputProperties flags → iOS (what is similar)

Legacy iframe sends one JSON blob per fieldEvent with separate booleans. iOS still validates the same rules — it exposes a different shape:

You cannot mirror iframe logic that branches on luhnValid separately from validNumber (e.g. show “checksum failed” while length rules still pass). Use isValid and your own copy, or onValidationChange.

All Gap and N/A iframe APIs are listed in the 1:1 mapping tables below — not only in this summary.

Use onFieldStateChange for scheme and digit counts — never log raw PAN/CVV or parse onChange ciphertext (opaque on .cardNumber and .cvc).

Legacy iFrame (JavaScript) 1:1 mapping

If you integrated Spreedly iFrame v1 (iframe-v1.min.js) in a WebView or mobile browser, use these tables to find the Checkout iOS pattern. Official legacy references: iFrame UI, iFrame events.

Step-by-step by topic

Initialization and configuration

Validation and field state (headless)

Tokenization, reset, and listeners

Recache, errors, 3DS

Mask and display (iframe toggleMask / setNumberFormat)

The iframe has no eye icon inside number or CVV iframes. Mask/reveal is merchant-owned UI calling Spreedly.shared().setNumberFormat(_:) or toggleMask() on the main thread.

iframe prettyFormat vs iOS .pretty

• Match: grouped spaced digits with the full PAN visible on focus and blur (iframe prettyFormat).
• Use .plain when you want all digits visible without spacing (iframe plainFormat).
• Use .masked or toggleMask() for * on every digit (iframe maskedFormat / toggleMask).
• setNumberFormat(.pretty) from masked unmasks the PAN only; CVV may stay masked until you set plain/masked or call toggleMask().
• toggleMask() does not select Pretty — call setNumberFormat(.pretty) for grouped spacing.

Full table: Display formats.

SPLTextField(type: .cardNumber, title: "Card number", isRequired: true)
SPLTextField(type: .cvc, title: "CVC", isRequired: true)

Spreedly.shared().setNumberFormat(.pretty)   // iframe prettyFormat — grouped, all digits visible
Spreedly.shared().setNumberFormat(.plain)    // iframe plainFormat
Spreedly.shared().setNumberFormat(.masked)   // iframe maskedFormat — `*` on PAN + CVV

Button("toggleMask()") { Spreedly.shared().toggleMask() }  // plain ↔ masked (not Pretty)

Objective-C:

[[Spreedly shared] setNumberFormatWithCardNumberFormatRawValue:2]; // 0=pretty, 1=plain, 2=masked
[[Spreedly shared] setNumberFormatWithType:@"maskedFormat"];
[[Spreedly shared] toggleMask];

Read Spreedly.shared().hostedCardDisplayState for UI labels only — do not assign mask flags directly. Full reference: PAN/CVV display.

PAN + CVV share one display state: Spreedly.shared().setNumberFormat / toggleMask apply to both headless .cardNumber and .cvc fields. Unlike separate iframe embeds with per-field state.

SPLTextField.forceMaskOnLifecycleStop (default true) — masks revealed PAN when the app backgrounds; does not replace toggleMask(). See CHANGELOG.

Express: seed layout with CardFormDropInDisplayConfig(cardNumberFormat:); mask APIs still apply from merchant UI outside the sheet.

Field-state observability (headless)

Legacy fieldEvent / inputProperties let merchants drive BIN UX, pay-button state, and validation while typing. iOS today (headless):

• Use SPLTextField.onFieldStateChange with HostedFieldState — preferred iframe-style channel: INPUT, FOCUS, BLUR, VALIDATION, PAN_MASK_CHANGED; includes cardScheme, numberLength / cvvLength, iin, isValid, isEmpty, isFocused, isPanMasked.
• HostedFieldState.isValid replaces iframe validNumber, validCvv, and luhnValid (validation still runs; booleans are combined).
• The SDK does not ship brand image assets — use trailingIcon (SwiftUI) or trailingIconViewFactory (UIKit) on .cardNumber only.

Iframe event names → Swift cases: INPUT → .input, FOCUS → .focus, BLUR → .blur, VALIDATION → .validation, PAN_MASK_CHANGED → .panMaskChanged. The tables in this guide use iframe-style names for parity; Swift code compares against the HostedFieldEventType enum cases. Objective-C reads the enum's raw value or HostedFieldEventType... constants.

Card brand while typing: HostedFieldState.cardScheme + optional trailingIcon: (SwiftUI) or trailingIconViewFactory (UIKit) on headless PAN field only. SDK does not ship brand image assets.

SwiftUI vs UIKit / Objective-C:

Code samples (headless)

@State private var cardBrand: CardType?

SPLTextField(
    type: .cardNumber,
    title: "Card number",
    isRequired: true,
    onFieldStateChange: { state in
        if state.fieldType == .cardNumber {
            cardBrand = state.cardScheme
        }
    },
    trailingIcon: { scheme in
        Image(systemName: iconName(for: scheme))
    }
)

// Pre-submit gate — mirrors iframe validNumber / validCvv / luhnValid → use isValid (one flag per field)
var cardValid = false
SPLTextField(type: .cardNumber, title: "Card number", isRequired: true,
    onFieldStateChange: { state in
        if state.eventType == .validation || state.eventType == .input {
            cardValid = state.isValid
        }
    })
// guard cardValid && Spreedly.areAllFieldsValid(fieldTypes: [.cardNumber, .expirationMonth, .expirationYear, .cvc])

Objective-C:

fieldVC.onFieldStateChange = ^(HostedFieldState *state) { /* ... */ };
// Or: fieldVC.hostedFieldStateListener = self;  // HostedFieldStateListener

UIKit wrapper:

let fieldVC = SPLTextFieldViewController(field: .cardNumber, title: "Card number", isRequired: true, placeholder: nil, onValidationChange: nil)
fieldVC.onFieldStateChange = { state in /* HostedFieldState */ }

See custom-payment-forms.md and express-checkout.md.

Hosted field observability (summary)

IIN while typing (headless)

Iframe inputProperties.iin maps to HostedFieldState.iin on SPLTextField / SPLTextFieldViewController card-number callbacks only:

SPLTextField(type: .cardNumber, title: "Card number", isRequired: true,
    onFieldStateChange: { state in
        guard state.fieldType == .cardNumber, let prefix = state.iin else { return }
        // Drive BIN UI from prefix only — do not log with other payment data
    })

API lookup (reference)

Detailed inventory and extended mapping tables. For onboarding, start with Start here.

Public API inventory

Single checklist of merchant-facing APIs verified against the shipped SDK surface.

SDK-level

• Spreedly.isInitialized — true after successful signed setup
• Spreedly.setup(config:) / setupWithConfig(_:) — SDK configuration (Basic setup)
• Spreedly.areAllFieldsValid(fieldTypes:) — aggregate validation before tokenize
• SpreedlyUIManager.shared.areAllFieldsValid() — all registered fields
• getRegisteredFieldCount() / getInvalidFieldTypes() on SpreedlyUIManager.shared — pay-button gating (ObjC: getInvalidFieldTypes returns NSNumber raw values)
• EmailValidator.isValid(_:) — optional email gate
• Spreedly.shared().hostedCardDisplayState, setNumberFormat(_:), setNumberFormat(type:), toggleMask()
• SpreedlyUIManager.shared.setHostedCardDisplayState(_:) / resetHostedCardDisplayState()
• SpreedlyUIManager.shared.applySeparatedExpirationAutofill(month:year:excluding:)
• Spreedly.shared().setParam(parameter:value:) — ValidationParam
• Objective-C: hostedCardDisplayCardNumberFormatRawValue on [Spreedly shared]

Headless SPLTextField only

• Callbacks: onFieldStateChange, onFocusChanged, onFocus, onInputLength, onValidationChange, onChange
• HostedFieldState: fieldType, eventType, isFocused, isValid, isEmpty, cardScheme, numberLength, cvvLength, isPanMasked, iin
• forceMaskOnLifecycleStop, enableAutofill, trailingIcon / trailingIconViewFactory
• HostedFieldStateListener / hostedFieldStateListener

CardFormDropIn only

• DropInCoreFieldLabels, CardFormDropInDisplayConfig
• onProcessingResult — immediate validation only; token on subscribeToPaymentResults
• Not available: onFieldStateChange, per-field focus callbacks, custom PAN trailingIcon

Safe field-state observability (extended)

Extended mapping tables

Initialization and configuration (full)

Validation and field state (full)

Same rows as Validation and field state (headless) above, plus:

Release notes and docs

See also Headless PAN API quick reference.

Getting help

Next steps

• If you also support Android apps, review Migrate from iFrame to the Android Checkout SDK.
• If you also support React Native apps, review Migrate from iFrame to the React Native Checkout SDK.