How to Implement PayPal Fastlane in Adyen Salesforce Commerce Cloud

PayPal Fastlane enables one-click checkout by authenticating shoppers once and returning a PayPal payer ID and token, bypassing the full-screen PayPal redirect.

Implementing PayPal Fastlane in the Adyen Salesforce Commerce Cloud integration streamlines the checkout process by embedding a compact authentication button directly on the payment page. This specialized Adyen payment method detects eligible shoppers and renders a Fastlane watermark that eliminates traditional redirect friction. This guide covers the complete server-side detection, state management, and client-side initialization required to implement PayPal Fastlane according to the adyen/adyen-salesforce-commerce-cloud source code.

Understanding the PayPal Fastlane Architecture

The Fastlane flow consists of three distinct layers that coordinate between the server and client.

Server-Side Detection

The back-end determines whether Fastlane is available by checking if the current basket qualifies for the constants.PAYMENTMETHODS.FASTLANE payment type and ensuring the shopper is not already authenticated. This logic resides in src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js.

State Management with MobX

The MobX store (src/cartridges/app_adyen_SFRA/cartridge/config/store.js) maintains an observable fastlane object that persists the component instance and configuration across UI renders. This prevents redundant network calls when the checkout page updates.

Client-Side Component Lifecycle

The client initializes the Fastlane component, authenticates the shopper via email, and mounts a watermark button. These operations are orchestrated in src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/fastlane/index.js and triggered by the checkout:renderPaymentMethod event.

Server-Side Implementation: Exposing the Fastlane Flag

When the checkout page requests available payment methods (/Adyen-GetCheckoutPaymentMethods), the controller filters the Adyen response for Fastlane eligibility.

// src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js
const showFastlane =
  paymentMethods.paymentMethods.some(
    (pm) => pm.type === constants.PAYMENTMETHODS.FASTLANE,
  ) && !req.currentCustomer.raw.authenticated;

// response payload
res.json({
  …
  showFastlane,
  shopperEmail,
  …
});

If showFastlane is true and the shopper is a guest, the front-end receives the signal to render the Fastlane experience.

Client-Side Implementation: Initializing and Rendering Fastlane

The client-side flow involves three sequential steps: initializing the component, authenticating the user, and mounting the UI watermark.

Initializing the Fastlane Component

The initFastlane function calls window.AdyenWeb.initializeFastlane with the checkout configuration. In test environments, it forces the consent dialog for debugging purposes.

// src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/fastlane/index.js
async function initFastlane() {
  store.fastlane.component = await window.AdyenWeb.initializeFastlane({
    …store.checkoutConfiguration,
    forceConsentDetails:
      store.checkoutConfiguration.environment === constants.ENVIRONMENTS.TEST,
  });
}

Authenticating the Shopper

The fastlaneAuthenticate function sends the shopper’s email to the component to obtain an authentication token. The resulting configuration (including the PayPal merchant ID) is saved back to store.fastlane.configuration for later use.

Mounting the Fastlane Watermark

Once authenticated, mountFastlaneWatermark inserts a small PayPal-branded element (#watermark-container) next to the standard PayPal button. This transforms the button into the Fastlane experience.

The renderFastlane function orchestrates these steps and guards against parallel execution using an isFastlaneRendering flag.

// src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/index.js
async function renderFastlane(shopperEmail) {
  if (isFastlaneRendering) return;
  isFastlaneRendering = true;
  try {
    await fastlaneAuthenticate(shopperEmail); // gets token + config
    await mountFastlaneWatermark(document.querySelector('#fastlane-watermark'));
  } finally {
    isFastlaneRendering = false;
  }
}

Configuring PayPal Fastlane Settings

The PayPalFastlaneConfig class extends standard PayPal configuration with Fastlane-specific options. It forces showPayButton: true and defines an onSubmit handler that serializes component state to the hidden #adyenStateData field before submitting.

// src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/paymentMethodsConfiguration/paypal/paypalFastlaneConfig.js
class PayPalFastlaneConfig {
  …
  getConfig() {
    return {
      …this.store?.fastlane?.configuration,
      showPayButton: true,
      onSubmit: this.onSubmit,
    };
  }
}

This configuration is registered under the fastlane key in the main payment methods configuration object (src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/paymentMethodsConfiguration/index.js), ensuring the UI renders the watermark when the checkout:renderPaymentMethod event fires.

Summary

• PayPal Fastlane is detected server-side in getCheckoutPaymentMethods.js by checking for the FASTLANE payment method type and ensuring the shopper is unauthenticated.
• The MobX store persists the Fastlane component instance and configuration across renders to prevent duplicate initialization.
• Client-side initialization occurs through initFastlane, which calls window.AdyenWeb.initializeFastlane with environment-specific settings.
• Authentication happens via fastlaneAuthenticate, which exchanges the shopper email for a token and merchant configuration.
• The Fastlane watermark is mounted using mountFastlaneWatermark, transforming the standard PayPal button into a one-click checkout experience.
• Configuration is handled by PayPalFastlaneConfig, which forces showPayButton: true and manages form submission via onSubmit.

Frequently Asked Questions

What is PayPal Fastlane and how does it differ from standard PayPal checkout?

PayPal Fastlane is a specialized Adyen payment method that allows shoppers to authenticate once and complete future purchases with a single click. Unlike standard PayPal checkout, which redirects the shopper to a full-screen PayPal page, Fastlane displays a compact watermark button on the merchant's checkout page and returns a PayPal payer ID and token without leaving the site.

How does the server determine whether to show the Fastlane option?

The server evaluates Fastlane eligibility in src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js by checking two conditions: the Adyen payment methods response must include the FASTLANE type, and the current customer must not be authenticated (!req.currentCustomer.raw.authenticated). Only guest shoppers see the Fastlane button.

Where is the Fastlane component state stored between checkout interactions?

The Fastlane component instance and its configuration are stored in the MobX observable store defined in src/cartridges/app_adyen_SFRA/cartridge/config/store.js. The fastlane object persists the component across UI re-renders, preventing redundant network calls to window.AdyenWeb.initializeFastlane when the checkout page updates dynamically.

What triggers the Fastlane watermark to appear on the checkout page?

The watermark renders when the checkout:renderPaymentMethod event fires and the server has returned showFastlane: true along with a shopperEmail. The renderFastlane function in src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/index.js orchestrates the initialization, authentication, and mounting of the watermark via mountFastlaneWatermark.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}