Migrate from iFrame to the Web SDK

// Legacy
Spreedly.setParam('first_name', 'John');
Spreedly.setParam('last_name',  'Doe');
Spreedly.setParam('month',      '12');
Spreedly.setParam('year',       '2028');
Spreedly.setParam('email',      '[email protected]');
Spreedly.setParam('address1',   '123 Main St');
Spreedly.setParam('shipping_city', 'Boston');
Spreedly.setParam('eligible_for_card_updater', true);
Spreedly.setParam('metadata',   { order_id: 'ORDER-123' });
Spreedly.setParam('allow_blank_name', true);
Spreedly.tokenizeCreditCard();

// Checkout Web SDK — every legacy setParam field has a typed slot
sdk.submit(
  {
    first_name: 'John',
    last_name:  'Doe',
    month:      '12',
    year:       '2028',
    email:      '[email protected]',
    address1:   '123 Main St',
    shipping_city: 'Boston',
    eligible_for_card_updater: true,
  },
  {
    metadata: { order_id: 'ORDER-123' },
    allow_blank_name: true,
  }
);

type HostedFieldsFormData = {
  // Mandatory (matches legacy)
  first_name: string;
  last_name:  string;
  month:      string;     // 'MM'
  year:       string;     // 'YYYY'

  // Cardholder
  full_name?:    string;
  email?:        string;
  company?:      string;
  phone_number?: string;

  // Billing address
  address1?: string;
  address2?: string;
  city?:     string;
  state?:    string;
  zip?:      string;
  country?:  string;

  // Shipping address (every legacy `shipping_*` field)
  shipping_address1?:    string;
  shipping_address2?:    string;
  shipping_city?:        string;
  shipping_state?:       string;
  shipping_zip?:         string;
  shipping_country?:     string;
  shipping_phone_number?: string;

  // Legacy boolean flag (was `permittedBooleanParams` in the iframe)
  eligible_for_card_updater?: boolean;
};

// Legacy
Spreedly.setRecache('RETAINED-PM-TOKEN', { last_four_digits: '4242', card_type: 'visa' });
Spreedly.on('recacheReady', () => { /* prompt for CVV */ });
Spreedly.recache();
Spreedly.on('recache', (token, pm) => { /* success */ });

// Checkout Web SDK (Hosted Fields)
sdk.setRecache('RETAINED-PM-TOKEN', {
  card_type: 'visa',
  last_four_digits: '4242',
  storage_state: 'retained',
  month: '12',
  year: '2028',
});
sdk.on('recacheReady', () => { /* prompt for CVV */ });
sdk.recache();
sdk.on('recacheSuccess', (response) => { /* response.payment_method... */ });

// Legacy
Spreedly.on('3ds:status', (event) => {
  switch (event.action) {
    case 'challenge':  /* show modal */ break;
    case 'succeeded':  /* success */    break;
    case 'error':      /* failure */    break;
  }
});
const lifecycle = new Spreedly.ThreeDS.Lifecycle({
  environmentKey,
  hiddenIframeLocation:    'device-fingerprint',
  challengeIframeLocation: 'challenge',
  transactionToken,
});
lifecycle.start();

// Checkout Web SDK
const lifecycle = new SpreedlyThreeDSLifecycle({
  transactionToken,
  hiddenIframeLocation:    'device-fingerprint',
  challengeIframeLocation: 'challenge-container',
  environmentKey,
  callbacks: {
    onChallenge: (e) => { /* show modal */ },
    onSuccess:   (e) => { /* success */    },
    onError:     (e) => { /* failure */    },
  },
});
lifecycle.start();

<!-- Legacy: hand-built form -->
<form action="https://core.spreedly.com/v1/payment_methods" method="POST">
  <input name="environment_key" value="..." />
  <input name="payment_method_type" value="paypal" />
  <input name="redirect_url" value="https://merchant/handle-redirect" />
  ...
</form>

// Checkout Web SDK — API flow (recommended)
sdk.on('offsiteTokenGenerated', ({ token, paymentMethodType }) => {
  // POST token to your backend → run the gateway purchase
});
sdk.on('offsitePaymentError', (err) => { /* ... */ });

sdk.setupOffsitePayment({
  paymentMethodType: 'paypal', // or 'pix', 'boleto_bancario', 'oxxo', 'nupay', ...
  email: '[email protected]',
  fullName: 'Ana Santos',
  // ... optional billing/contact fields
});
sdk.submitOffsitePayment();

// Legacy
const element = Spreedly.createStripePaymentElement({
  publishableKey,
  clientSecret,
  transactionToken,
  paymentElement: '#payment-element',
  appearance,
});
element.confirmPayment();

// Checkout Web SDK
const stripeApm = new SpreedlyStripeAPM({
  publishableKey,
  clientSecret,
  transactionToken,
  paymentElement: 'stripe-payment-element', // element ID, not selector
  appearance,
});
stripeApm.mount();
await stripeApm.confirmPayment();

// Legacy
Spreedly.createBraintreePaymentElements({
  callbackFunction:  handlePaymentResult,
  transactionToken,
  paymentElements:   { paypal: 'paypal-button', venmo: 'venmo-button' },
  environmentKey,
});

// Checkout Web SDK
const braintree = new SpreedlyBraintree({
  transactionToken,
  environmentKey,
  paymentElements: { paypal: 'paypal-button', venmo: 'venmo-button' },
  onPaymentResult: handlePaymentResult,
  onButtonAction:  handleButtonAction, // optional
  style:           { paypal: { color: 'gold', shape: 'rect', height: 45 } }, // optional
});
const result = await braintree.mount();

const sdk = new SpreedlyExpressCheckout({
  environment_key, certificate_token, nonce, signature, timestamp,
});

sdk.on('ready',          () => {});
sdk.on('tokenGenerated', (resp) => {});
sdk.on('error',          (err)  => {});
sdk.on('close',          () => {});

const checkout = sdk.expressCheckout({
  parentContainerId: 'checkout-container', // omit for full-screen dialog mode
});

sdk.updateTextElement('title',          'Complete Your Purchase');
sdk.updateTextElement('submitBtnText',  'Pay $99.00');
sdk.addField('phone_number', { /* ... */ });
sdk.removeField('company');
sdk.setFieldConfig('first_name', { /* ... */ });

sdk.close(true);

sdk.expressCheckout({
  parentContainerId: 'checkout-container',
  uiConfig: {
    cardPaymentFormFields: {
      // Default mandatory fields are merged in automatically; just add the extras.
      email:    { fieldName: 'email',    label: 'Email',    isRequired: true,  size: 12, isMasked: false, placeholder: '[email protected]', styles: {} },
      address1: { fieldName: 'address1', label: 'Address 1', isRequired: false, size: 12, isMasked: false, placeholder: '123 Main St',     styles: {} },
    },
  },
  submitParams: {
    metadata: { order_id: 'ORDER-123' },
    eligible_for_card_updater: true,
  },
});