Skip to main content

Migration to Checkout V1 (iFrame fields)

The Checkout SDK renders card payment fields inside secure iFrames instead of native browser inputs. This change reduces your PCI DSS scope — sensitive card data (card number, expiry, CVV, and cardholder name) no longer enters your page.

important

Native card inputs will be fully removed on June 3, 2026. After that date, all checkout sessions will use iFrame-based fields exclusively.

Is action required?​

Update your SDK dependency to v1.0.0:

npm install @odus/checkout@^1.0.0

Beyond the version bump, the migration is automatic and server-managed. Your existing SDK initialization code, callbacks, and payment flow remain unchanged:

  • OdusCheckout / OdusElements — same constructor options
  • mount() — same behavior
  • associatePayment() — same behavior
  • onPaymentSucceeded / onPaymentFailed — same callback signatures

If you have not customized the checkout beyond the documented appearance configuration, no additional changes are needed.

What changed​

AspectBefore (native inputs)After (iFrame fields)
Card number, expiry, CVV, cardholder nameRendered as <input> elements directly in your page DOMRendered inside secure iFrames managed by Odus
PCI scopeCard data passes through your pageCard data is isolated — never touches your page
Field loadingImmediateBrief skeleton placeholder while iFrames initialize

Behavioral differences​

You and your customers may notice these minor UX changes:

  1. Loading skeleton — Card fields display a brief placeholder animation while iFrames load. This typically resolves within 1–2 seconds on a standard connection.

Styling considerations​

If your integration relies on custom CSS that directly targets card input elements (e.g., styling .form-input or input[name="cardNumber"]), those selectors will no longer reach the fields inside iFrames.

Instead, use the SDK's built-in styling options:

  • Drop-in Checkout — configure appearance.styles (borderRadius, fontFamily, fontSize, textColor) as documented in the Appearance guide
  • Elements — use applyTheme() or per-element setTheme() as documented in the Theming guide
tip

The appearance.styles.borderRadius, appearance.styles.fontFamily, and appearance.styles.fontSize options are fully applied to iFrame fields. If your checkout already uses these options, the fields will look identical to before.