swell-js 5.9.3 → 5.10.0

package/dist/payment.mjs

@@ -677,25 +677,184 @@ async function createPaymentMethod(stripe, cardElement, cart) {
     billing_details: billingDetails,
   });
 
-  return error
-    ? { error }
-    : {
-        gateway: 'stripe',
-        token: paymentMethod.id,
-        last4: paymentMethod.card.last4,
-        exp_month: paymentMethod.card.exp_month,
-        exp_year: paymentMethod.card.exp_year,
-        brand: paymentMethod.card.brand,
-        display_brand: paymentMethod.card.display_brand,
-        address_check: paymentMethod.card.checks.address_line1_check,
-        cvc_check: paymentMethod.card.checks.cvc_check,
-        zip_check: paymentMethod.card.checks.address_postal_code_check,
-      };
+  return error ? { error } : mapCardPaymentMethod(paymentMethod);
 }
 
 /**
+ * Elements group options of the card Payment Element for the cart amount,
+ * matching the intent StripeCardPayment#_createIntent creates.
+ *
+ * @param {Cart} cart
+ * @returns {import('@stripe/stripe-js').StripeElementsOptionsMode}
+ */
+function getCardElementsOptions(cart) {
+  const { capture_total, auth_total } = cart;
+  const currency = cart.currency || 'USD';
+  const stripeCurrency = currency.toLowerCase();
+
+  // the card is only stored when the amount is not chargeable, no intent is created
+  if (!isStripeChargeableAmount(capture_total, cart.currency)) {
+    return {
+      mode: 'setup',
+      currency: stripeCurrency,
+      paymentMethodTypes: ['card'],
+    };
+  }
+
+  return {
+    mode: 'payment',
+    amount: stripeAmountByCurrency(currency, capture_total + (auth_total || 0)),
+    currency: stripeCurrency,
+    captureMethod: 'manual',
+    setupFutureUsage: 'off_session',
+    paymentMethodTypes: ['card'],
+  };
+}
+
+/**
+ * Elements group options of the iDEAL Payment Element,
+ * matching the intent StripeIDealPayment#_createIntent creates.
+ *
+ * @param {Cart} cart
+ * @returns {import('@stripe/stripe-js').StripeElementsOptionsMode}
+ */
+function getIDealElementsOptions(cart) {
+  const { capture_total } = cart;
+  const currency = cart.currency || 'EUR';
+
+  return {
+    mode: 'payment',
+    amount: stripeAmountByCurrency(currency, capture_total),
+    currency: currency.toLowerCase(),
+    paymentMethodTypes: ['ideal'],
+  };
+}
+
+/**
+ * Creates an Elements group without an intent and mounts the Payment Element
+ * into `#${params.elementId || 'payment-element'}`.
+ *
+ * @param {Stripe} stripe
+ * @param {import('@stripe/stripe-js').StripeElementsOptionsMode} elementsOptions
+ * @param {object} params
+ * @returns {import('@stripe/stripe-js').StripeElements}
+ */
+function createPaymentElements(stripe, elementsOptions, params) {
+  const elements = stripe.elements({
+    ...params.config,
+    ...elementsOptions,
+    // lets stripe.createPaymentMethod read the Payment Element
+    paymentMethodCreation: 'manual',
+    ...(params.appearance && { appearance: params.appearance }),
+  });
+
+  createElement('payment', elements, {
+    ...params,
+    options: {
+      layout: 'tabs',
+      fields: { billingDetails: 'never' },
+      // wallets are separate express buttons
+      wallets: { applePay: 'never', googlePay: 'never' },
+      ...params.options,
+    },
+  });
+
+  return elements;
+}
+
+/**
+ * Creates a PaymentMethod from the Payment Element.
+ * Brings the Elements amount up to date with the cart first.
+ *
  * @param {Stripe} stripe
- * @param {import('@stripe/stripe-js').StripeIdealBankElement} element
+ * @param {import('@stripe/stripe-js').StripeElements} elements
+ * @param {import('@stripe/stripe-js').StripeElementsOptionsMode} elementsOptions
+ * @param {Cart} cart
+ * @returns {Promise<import('@stripe/stripe-js').PaymentMethodResult>}
+ */
+async function createPaymentMethodFromElements(
+  stripe,
+  elements,
+  elementsOptions,
+  cart,
+) {
+  // setup mode stores the card without an intent, there is no amount to update
+  if (elementsOptions.mode === 'payment') {
+    await elements.update(elementsOptions);
+  }
+
+  const { error } = await elements.submit();
+
+  if (error) {
+    return { error };
+  }
+
+  const { address, ...details } = getBillingDetails(cart);
+
+  // fields the Payment Element does not collect must all be passed, null when unknown
+  return stripe.createPaymentMethod({
+    elements,
+    params: {
+      billing_details: {
+        name: null,
+        email: null,
+        phone: null,
+        ...details,
+        address: {
+          line1: null,
+          line2: null,
+          city: null,
+          state: null,
+          postal_code: null,
+          country: null,
+          ...address,
+        },
+      },
+    },
+  });
+}
+
+/**
+ * @param {Stripe} stripe
+ * @param {import('@stripe/stripe-js').StripeElements} elements
+ * @param {Cart} cart
+ */
+async function createCardPaymentMethodFromElements(
+  stripe,
+  elements,
+  cart,
+) {
+  const { paymentMethod, error } = await createPaymentMethodFromElements(
+    stripe,
+    elements,
+    getCardElementsOptions(cart),
+    cart,
+  );
+
+  return error ? { error } : mapCardPaymentMethod(paymentMethod);
+}
+
+/**
+ * @param {import('@stripe/stripe-js').PaymentMethod} paymentMethod
+ */
+function mapCardPaymentMethod(paymentMethod) {
+  return {
+    gateway: 'stripe',
+    token: paymentMethod.id,
+    last4: paymentMethod.card.last4,
+    exp_month: paymentMethod.card.exp_month,
+    exp_year: paymentMethod.card.exp_year,
+    brand: paymentMethod.card.brand,
+    display_brand: paymentMethod.card.display_brand,
+    address_check: paymentMethod.card.checks.address_line1_check,
+    cvc_check: paymentMethod.card.checks.cvc_check,
+    zip_check: paymentMethod.card.checks.address_postal_code_check,
+  };
+}
+
+/**
+ * @param {Stripe} stripe
+ * @param {import('@stripe/stripe-js').StripeIdealBankElement | {}} element `{}` when there is no idealBank element
  * @param {Cart} cart
  */
 async function createIDealPaymentMethod(stripe, element, cart) {
@@ -883,6 +1042,29 @@ function isStripeChargeableAmount(amount, currency) {
   return !minAmount || amount >= minAmount;
 }
 
+// The cart keeps what checkout v1 keeps, so the next tokenize can retrieve and reuse
+// the intent; the vault cancels the replaced ones when the order is paid
+const cartIntent = (cart, intent) => {
+  const exIntent = cart.billing?.intent?.stripe;
+
+  return {
+    id: intent.id,
+    client_secret: intent.client_secret,
+    amount: intent.amount,
+    currency: intent.currency,
+    ...(Boolean(cart.auth_total) && { auth_amount: cart.auth_total }),
+    ...(exIntent?.id &&
+      exIntent.id !== intent.id && {
+        canceled: [...(exIntent.canceled || []), exIntent.id],
+      }),
+  };
+};
+
+const intentAmount = ({ currency, capture_total, auth_total }) =>
+  stripeAmountByCurrency(currency, capture_total + auth_total);
+
+const intentCurrency = ({ currency }) => (currency || 'USD').toLowerCase();
+
 /** @typedef {import('@stripe/stripe-js').Stripe} Stripe */
 /** @typedef {import('@stripe/stripe-js').StripeCardElement} StripeCardElement */
 /** @typedef {import('@stripe/stripe-js').StripeCardNumberElement} StripeCardNumberElement */
@@ -926,9 +1108,30 @@ class StripeCardPayment extends Payment {
     StripeCardPayment.stripeElement = stripeElement;
   }
 
-  async createElements() {
+  /** @returns {import('@stripe/stripe-js').StripeElements} */
+  get stripeElements() {
+    return StripeCardPayment.stripeElements;
+  }
+
+  /** @param {import('@stripe/stripe-js').StripeElements} stripeElements */
+  set stripeElements(stripeElements) {
+    StripeCardPayment.stripeElements = stripeElements;
+  }
+
+  /** @param {import('../../../types').Cart} cart */
+  async createElements(cart) {
     await this.loadScripts(this.scripts);
 
+    if (this.params.paymentElement) {
+      this.stripeElements = createPaymentElements(
+        this.stripe,
+        getCardElementsOptions(cart),
+        this.params,
+      );
+
+      return;
+    }
+
     const elements = this.stripe.elements(this.params.config);
 
     if (this.params.separateElements) {
@@ -941,18 +1144,26 @@ class StripeCardPayment extends Payment {
   }
 
   async tokenize() {
-    if (!this.stripeElement) {
+    const { paymentElement, paymentMethod: token } = this.params;
+
+    if (token) {
+      return this._authorizePaymentMethod(token);
+    }
+
+    if (!(paymentElement ? this.stripeElements : this.stripeElement)) {
       throw new Error('Stripe payment element is not defined');
     }
 
     await this.loadScripts(this.scripts);
 
     const cart = await this.getCart();
-    const paymentMethod = await createPaymentMethod(
-      this.stripe,
-      this.stripeElement,
-      cart,
-    );
+    const paymentMethod = paymentElement
+      ? await createCardPaymentMethodFromElements(
+          this.stripe,
+          this.stripeElements,
+          cart,
+        )
+      : await createPaymentMethod(this.stripe, this.stripeElement, cart);
 
     if (paymentMethod.error) {
       throw new Error(paymentMethod.error.message);
@@ -962,8 +1173,12 @@ class StripeCardPayment extends Payment {
       paymentMethod.test = true;
     }
 
-    // should save payment method data when payment amount is not chargeable
-    if (!isStripeChargeableAmount(cart.capture_total, cart.currency)) {
+    // should save payment method data when payment amount is not chargeable,
+    // or when the host collects the card without authorizing it now
+    if (
+      !isStripeChargeableAmount(cart.capture_total, cart.currency) ||
+      this.params.createIntent === false
+    ) {
       await this.updateCart({
         billing: {
           method: 'card',
@@ -974,60 +1189,129 @@ class StripeCardPayment extends Payment {
       return this.onSuccess();
     }
 
-    const intent = await this._createIntent(cart, paymentMethod);
+    const intent = await this._authorizeIntent(cart, paymentMethod.token);
 
     await this.updateCart({
       billing: {
         method: 'card',
         card: paymentMethod,
-        intent: {
-          stripe: {
-            id: intent.id,
-            ...(Boolean(cart.auth_total) && {
-              auth_amount: cart.auth_total,
-            }),
-          },
-        },
+        intent: { stripe: cartIntent(cart, intent) },
       },
     });
 
     this.onSuccess();
   }
 
-  async authenticate(payment) {
-    const { transaction_id: id, card: { token } = {} } = payment;
+  // A card the shopper already has (a saved card, a wallet's payment method) gets
+  // the intent and 3-D Secure of a new one; other cards are authorized with the order
+  async _authorizePaymentMethod(token) {
+    const cart = await this.getCart();
 
-    const intent = await this.updateIntent({
-      gateway: 'stripe',
-      intent: { id, payment_method: token },
-    });
+    if (
+      token.startsWith('pm_') &&
+      isStripeChargeableAmount(cart.capture_total, cart.currency) &&
+      this.params.createIntent !== false
+    ) {
+      await this.loadScripts(this.scripts);
+
+      const intent = await this._authorizeIntent(cart, token);
 
-    if (intent.error) {
-      throw new Error(intent.error.message);
+      if (intent.id !== cart.billing?.intent?.stripe?.id) {
+        await this.updateCart({
+          billing: {
+            method: 'card',
+            intent: { stripe: cartIntent(cart, intent) },
+          },
+        });
+      }
     }
 
-    await this.loadScripts(this.scripts);
+    this.onSuccess();
+  }
 
+  // Reuses the cart's intent while Stripe still has it for this card and amount
+  async _authorizeIntent(cart, token) {
+    const exIntent = cart.billing?.intent?.stripe;
+    const intent =
+      (exIntent?.client_secret &&
+        (await this._retrieveIntent(cart, exIntent, token))) ||
+      (await this._createIntent(cart, token));
+
+    switch (intent.status) {
+      case 'requires_capture':
+        break;
+
+      case 'requires_confirmation':
+        await this._confirmCardPayment(intent);
+        break;
+
+      case 'requires_action':
+      case 'requires_source_action': {
+        const actionResult = await this.stripe.handleCardAction(
+          intent.client_secret,
+        );
+
+        if (actionResult.error) {
+          throw new Error(actionResult.error.message);
+        }
+
+        break;
+      }
+
+      default:
+        throw new Error(`Unsupported intent status: ${intent.status}`);
+    }
+
+    return intent;
+  }
+
+  async _retrieveIntent(cart, exIntent, token) {
+    const { paymentIntent: intent, error } =
+      await this.stripe.retrievePaymentIntent(exIntent.client_secret);
+
+    const matches =
+      !error &&
+      intent.amount === intentAmount(cart) &&
+      intent.currency === intentCurrency(cart) &&
+      intent.payment_method === token &&
+      !['canceled', 'requires_source', 'requires_payment_method'].includes(
+        intent.status,
+      );
+
+    return matches ? intent : null;
+  }
+
+  async authenticate(payment) {
+    const { transaction_id: id, card: { token } = {} } = payment;
+
+    // The payment is re-queried whatever happens here: an intent the shopper
+    // already confirmed can't be updated, and the payment must still learn it
     try {
-      const result = await this._confirmCardPayment(intent);
+      const intent = await this.updateIntent({
+        gateway: 'stripe',
+        intent: { id, payment_method: token },
+      });
 
-      return result;
+      if (intent.error) {
+        throw new Error(intent.error.message);
+      }
+
+      await this.loadScripts(this.scripts);
+
+      return await this._confirmCardPayment(intent);
     } finally {
       await this.resetAsyncPayment(payment.id);
     }
   }
 
-  async _createIntent(cart, paymentMethod) {
-    const { account, currency, capture_total, auth_total } = cart;
-    const stripeCustomer = account && account.stripe_customer;
-    const stripeCurrency = (currency || 'USD').toLowerCase();
-    const amount = stripeAmountByCurrency(currency, capture_total + auth_total);
+  async _createIntent(cart, token) {
+    const stripeCustomer = cart.account && cart.account.stripe_customer;
     const intent = await this.createIntent({
       gateway: 'stripe',
       intent: {
-        amount,
-        currency: stripeCurrency,
-        payment_method: paymentMethod.token,
+        amount: intentAmount(cart),
+        currency: intentCurrency(cart),
+        payment_method: token,
         capture_method: 'manual',
         setup_future_usage: 'off_session',
         ...(stripeCustomer ? { customer: stripeCustomer } : {}),
@@ -1038,20 +1322,6 @@ class StripeCardPayment extends Payment {
       throw new Error('Stripe payment intent is not defined');
     }
 
-    switch (intent.status) {
-      case 'requires_capture':
-      case 'requires_confirmation':
-        break;
-
-      default:
-        throw new Error(`Unsupported intent status: ${intent.status}`);
-    }
-
-    // Confirm the payment intent
-    if (intent.status === 'requires_confirmation') {
-      await this._confirmCardPayment(intent);
-    }
-
     return intent;
   }
 
@@ -1119,24 +1389,58 @@ class StripeIDealPayment extends Payment {
     StripeIDealPayment.stripeElement = stripeElement;
   }
 
-  async createElements() {
+  /** @returns {import('@stripe/stripe-js').StripeElements} */
+  get stripeElements() {
+    return StripeIDealPayment.stripeElements;
+  }
+
+  /** @param {import('@stripe/stripe-js').StripeElements} stripeElements */
+  set stripeElements(stripeElements) {
+    StripeIDealPayment.stripeElements = stripeElements;
+  }
+
+  /** @param {import('../../../types').Cart} cart */
+  async createElements(cart) {
     await this.loadScripts(this.scripts);
 
+    if (this.params.paymentElement) {
+      this.stripeElements = createPaymentElements(
+        this.stripe,
+        getIDealElementsOptions(cart),
+        this.params,
+      );
+
+      return;
+    }
+
     const elements = this.stripe.elements(this.params.config);
 
     this.stripeElement = createElement('idealBank', elements, this.params);
   }
 
   async tokenize() {
-    if (!this.stripeElement) {
+    const { paymentElement } = this.params;
+
+    if (paymentElement && !this.stripeElements) {
       throw new Error('Stripe payment element is not defined');
     }
 
     await this.loadScripts(this.scripts);
 
     const cart = await this.getCart();
-    const { paymentMethod, error: paymentMethodError } =
-      await createIDealPaymentMethod(this.stripe, this.stripeElement, cart);
+    const { paymentMethod, error: paymentMethodError } = paymentElement
+      ? await createPaymentMethodFromElements(
+          this.stripe,
+          this.stripeElements,
+          getIDealElementsOptions(cart),
+          cart,
+        )
+      : // without an idealBank element the shopper picks the bank on the iDEAL page
+        await createIDealPaymentMethod(
+          this.stripe,
+          this.stripeElement || {},
+          cart,
+        );
 
     if (paymentMethodError) {
       throw new Error(paymentMethodError.message);
@@ -1147,6 +1451,38 @@ class StripeIDealPayment extends Payment {
     await this.stripe.handleCardAction(intent.client_secret);
   }
 
+  async handleRedirect(queryParams) {
+    const { redirect_status, payment_intent_client_secret } = queryParams;
+
+    if (redirect_status !== 'succeeded') {
+      throw new UnableAuthenticatePaymentMethodError();
+    }
+
+    await this.loadScripts(this.scripts);
+
+    const { paymentIntent, error } = await this.stripe.retrievePaymentIntent(
+      payment_intent_client_secret,
+    );
+
+    if (error) {
+      throw new Error(error.message);
+    }
+
+    if (
+      !['succeeded', 'requires_capture', 'processing'].includes(
+        paymentIntent.status,
+      )
+    ) {
+      throw new Error(
+        paymentIntent.last_payment_error?.message ||
+          `Unsupported intent status (${paymentIntent.status})`,
+      );
+    }
+
+    // the cart's billing was written in `tokenize`
+    this.onSuccess();
+  }
+
   /**
    * @param {object} cart
    * @param {import('@stripe/stripe-js').PaymentMethod} paymentMethod
@@ -1164,7 +1500,8 @@ class StripeIDealPayment extends Payment {
         payment_method_types: 'ideal',
         confirmation_method: 'manual',
         confirm: true,
-        return_url: window.location.href,
+        // `gateway` lets `handleRedirect` run on return; Stripe appends the intent and `redirect_status`
+        return_url: getReturnUrl(),
       },
     });
 
@@ -1196,6 +1533,14 @@ class StripeIDealPayment extends Payment {
   }
 }
 
+function getReturnUrl() {
+  const url = new URL(window.location.href);
+
+  url.searchParams.set('gateway', 'stripe');
+
+  return url.toString();
+}
+
 /** @typedef {import('@stripe/stripe-js').Stripe} Stripe */
 
 class StripeBancontactPayment extends Payment {
@@ -1515,6 +1860,7 @@ class StripeGooglePayment extends Payment {
   async _onPaymentMethod(event) {
     const {
       payerEmail,
+      payerName,
       paymentMethod: { id: paymentMethod, card, billing_details },
       shippingAddress,
       shippingOption,
@@ -1533,6 +1879,8 @@ class StripeGooglePayment extends Payment {
       }),
       billing: {
         ...this._mapBillingAddress(billing_details),
+        // a wallet may leave the card's address without a name; the payer's, when asked for, fills it
+        name: billing_details?.name || payerName,
         method: 'card',
         card: {
           gateway: 'stripe',
@@ -1771,6 +2119,7 @@ class StripeApplePayment extends Payment {
   async _onPaymentMethod(event) {
     const {
       payerEmail,
+      payerName,
       paymentMethod: { id: paymentMethod, card, billing_details },
       shippingAddress,
       shippingOption,
@@ -1789,6 +2138,8 @@ class StripeApplePayment extends Payment {
       }),
       billing: {
         ...this._mapBillingAddress(billing_details),
+        // a wallet may leave the card's address without a name; the payer's, when asked for, fills it
+        name: billing_details?.name || payerName,
         method: 'card',
         card: {
           gateway: 'stripe',
@@ -4219,6 +4570,238 @@ class QuickpayCardPayment extends Payment {
   }
 }
 
+// Saferpay payment-page brands per Swell method id; a list is joined because the
+// vault rejects arrays in `PaymentMethods`
+const PAYMENT_METHODS = {
+  card: [
+    'AMEX',
+    'DINERS',
+    'MAESTRO',
+    'JCB',
+    'VISA',
+    'BANCONTACT',
+    'MASTERCARD',
+    'SAFERPAYTEST',
+    'UNIONPAY',
+  ].join(','),
+  twint: 'TWINT',
+};
+
+/**
+ * @param {string} method 'card' or 'twint'
+ * @returns {string}
+ */
+function getSaferpayPaymentMethods(method) {
+  return PAYMENT_METHODS[method];
+}
+
+/**
+ * The Saferpay payment page request for a cart.
+ *
+ * @param {object} cart
+ * @param {string} method 'card' or 'twint'
+ * @returns {object}
+ */
+function getSaferpayPaymentPageData(cart, method) {
+  const currency = (cart.currency || 'USD').toUpperCase();
+  const returnUrl = window.location.origin + window.location.pathname;
+
+  return {
+    Payment: {
+      Amount: {
+        Value: amountInCents(currency, cart.grand_total || 0),
+        CurrencyCode: currency,
+      },
+      Description: 'Saferpay payment powered by Swell',
+    },
+    PaymentMethods: getSaferpayPaymentMethods(method),
+    ReturnUrls: {
+      Success: `${returnUrl}?gateway=saferpay&redirect_status=succeeded`,
+      Fail: `${returnUrl}?gateway=saferpay&redirect_status=failed`,
+      Abort: `${returnUrl}?gateway=saferpay&redirect_status=canceled`,
+    },
+  };
+}
+
+/**
+ * @param {object} state the Saferpay transaction state
+ * @returns {boolean}
+ */
+function isSaferpayCardPayment(state) {
+  const brand = state?.PaymentMeans?.Brand;
+
+  return Boolean(
+    state?.RegistrationResult?.Success &&
+      brand &&
+      PAYMENT_METHODS.card.split(',').includes(brand.PaymentMethod),
+  );
+}
+
+/**
+ * @param {object} state the Saferpay transaction state
+ * @returns {boolean}
+ */
+function isSaferpayTwintPayment(state) {
+  return state?.PaymentMeans?.Brand?.PaymentMethod === 'TWINT';
+}
+
+/**
+ * The card stored on the cart's billing from a Saferpay card state.
+ *
+ * @param {object} state
+ * @returns {object}
+ */
+function getSaferpayCard(state) {
+  const {
+    RegistrationResult: {
+      Alias: { Id: token },
+    },
+    PaymentMeans: {
+      Card: { ExpMonth: exp_month, ExpYear: exp_year, MaskedNumber },
+      Brand: { Name: brand },
+    },
+  } = state;
+
+  return {
+    token,
+    exp_month,
+    exp_year,
+    brand,
+    last4: MaskedNumber.slice(-4),
+    gateway: 'saferpay',
+  };
+}
+
+/**
+ * @param {object} state
+ * @returns {string | undefined}
+ */
+function getSaferpayTransactionId(state) {
+  return state?.Transaction?.Id;
+}
+
+/**
+ * Saferpay payment page: `tokenize` sends the shopper to Saferpay, and
+ * `handleRedirect` turns the returned transaction into the cart's billing.
+ * The card and TWINT classes share it; each one handles only the redirect of
+ * the method the cart was tokenized with, so a host can pass both.
+ */
+class SaferpayPayment extends Payment {
+  constructor(api, options, params, methods, methodId) {
+    super(api, options, params, methods[methodId]);
+    this.methodId = methodId;
+    this.cardMethod = methods.card;
+  }
+
+  async tokenize() {
+    const cart = await this.getCart();
+
+    // a card Saferpay already registered on this cart pays again without a new page visit
+    if (
+      this.methodId === 'card' &&
+      cart.billing?.card?.gateway === 'saferpay' &&
+      !this.params?.replace
+    ) {
+      return this.onSuccess();
+    }
+
+    const intent = await this.createIntent({
+      gateway: 'saferpay',
+      intent: getSaferpayPaymentPageData(cart, this.methodId),
+    });
+
+    if (!intent) {
+      throw new Error('Saferpay payment page is not defined');
+    }
+
+    await this.updateCart({
+      billing: {
+        method: this.methodId,
+        intent: {
+          saferpay: {
+            token: intent.token,
+          },
+        },
+      },
+    });
+
+    window.location.replace(intent.redirect_url);
+  }
+
+  async handleRedirect(queryParams) {
+    const { redirect_status: status } = queryParams;
+    const cart = await this.getCart();
+
+    // another Saferpay method of this host was tokenized: its instance answers
+    if (cart.billing?.method !== this.methodId) {
+      return;
+    }
+
+    switch (status) {
+      case 'succeeded':
+        return this._handleSuccessfulRedirect(cart);
+      case 'canceled':
+        return this.onCancel();
+      case 'failed':
+        throw new UnableAuthenticatePaymentMethodError();
+      default:
+        throw new Error(`Unknown redirect status: ${status}.`);
+    }
+  }
+
+  async _handleSuccessfulRedirect(cart) {
+    const token = cart.billing?.intent?.saferpay?.token;
+
+    if (!token) {
+      throw new Error('Saferpay transaction token is not defined');
+    }
+
+    const intent = await this.updateIntent({
+      gateway: 'saferpay',
+      intent: { token },
+    });
+
+    if (!intent) {
+      throw new Error('Saferpay transaction is not defined');
+    }
+
+    const { state } = intent;
+    const transaction = { transaction_id: getSaferpayTransactionId(state) };
+
+    if (isSaferpayCardPayment(state)) {
+      const card = getSaferpayCard(state);
+
+      if (!isLiveMode(this.cardMethod?.mode)) {
+        card.test = true;
+      }
+
+      await this.updateCart({
+        billing: { method: 'card', card, intent: { saferpay: transaction } },
+      });
+    } else if (isSaferpayTwintPayment(state)) {
+      await this.updateCart({
+        billing: { method: 'twint', intent: { saferpay: transaction } },
+      });
+    } else {
+      throw new Error('Payment method not supported by this gateway.');
+    }
+
+    this.onSuccess();
+  }
+}
+
+class SaferpayCardPayment extends SaferpayPayment {
+  constructor(api, options, params, methods) {
+    super(api, options, params, methods, 'card');
+  }
+}
+
+class SaferpayTwintPayment extends SaferpayPayment {
+  constructor(api, options, params, methods) {
+    super(api, options, params, methods, 'twint');
+  }
+}
+
 let convesioSettings = null;
 
 function getBaseConvesioApiUrl(mode) {
@@ -5899,6 +6482,33 @@ class PaymentController {
     return this.api.request('get', '/payments', id);
   }
 
+  /**
+   * Sends the shopper to the gateway when a submitted order waits for an
+   * asynchronous payment; resolves `true` after starting the redirect.
+   *
+   * @param {object} order the result of `cart.submitOrder()`
+   * @returns {Promise<boolean>}
+   */
+  async handleAsyncRedirect(order) {
+    const paymentId =
+      order?.authorized_payment_id ?? order?.authorizedPaymentId;
+
+    if (order?.status !== 'payment_pending' || !paymentId) {
+      return false;
+    }
+
+    const payment = await this.get(paymentId);
+    const url = payment?.async_data?.url ?? payment?.asyncData?.url;
+
+    if (!payment || payment.captured || !url) {
+      return false;
+    }
+
+    window.location.replace(url);
+
+    return true;
+  }
+
   async methods() {
     if (this.methodSettings) {
       return this.methodSettings;
@@ -5916,7 +6526,7 @@ class PaymentController {
       throw new Error('Payment element parameters are not provided');
     }
 
-    const paymentInstances = await this._createPaymentInstances();
+    const paymentInstances = await this._createPaymentInstances(params);
     const cart = await this.payment.getCart();
 
     await this._performPaymentAction(
@@ -5935,7 +6545,7 @@ class PaymentController {
       throw new Error('Tokenization parameters are not provided');
     }
 
-    const paymentInstances = await this._createPaymentInstances();
+    const paymentInstances = await this._createPaymentInstances(params);
 
     await this._performPaymentAction(paymentInstances, 'tokenize');
   }
@@ -5955,7 +6565,7 @@ class PaymentController {
 
     removeUrlParams();
 
-    const paymentInstances = await this._createPaymentInstances();
+    const paymentInstances = await this._createPaymentInstances(params);
 
     await this._performPaymentAction(
       paymentInstances,
@@ -6048,9 +6658,10 @@ class PaymentController {
   /**
    * @returns {Promise<Payment[]>}
    */
-  async _createPaymentInstances() {
+  // Takes the caller's params: this.params can change while the methods load (two createElements at once)
+  async _createPaymentInstances(callParams) {
     const paymentMethods = await this._getPaymentMethods();
-    const params = adjustParams(this.params);
+    const params = adjustParams(callParams);
 
     return Object.entries(params).reduce((acc, [method, params]) => {
       const methodSettings = paymentMethods[method];
@@ -6148,6 +6759,8 @@ class PaymentController {
         return this._getAmazonPaymentClass(gateway);
       case 'sezzle':
         return this._getSezzlePaymentClass(gateway);
+      case 'twint':
+        return this._getTwintPaymentClass(gateway);
       default:
         return null;
     }
@@ -6161,6 +6774,17 @@ class PaymentController {
         return QuickpayCardPayment;
       case 'convesiopay':
         return ConvesioCardPayment;
+      case 'saferpay':
+        return SaferpayCardPayment;
+      default:
+        return null;
+    }
+  }
+
+  _getTwintPaymentClass(gateway) {
+    switch (gateway) {
+      case 'saferpay':
+        return SaferpayTwintPayment;
       default:
         return null;
     }