Fastlane

SDK

Last updated: Aug 1st, 10:01am

Overview

PayPal Fastlane is a streamlined checkout experience that allows returning customers to authenticate and pay quickly using saved payment methods and shipping addresses. New customers can also use it for a smooth guest checkout experience.

Prerequisites

Before integrating PayPal Fastlane, ensure you have a PayPal sandbox account with appropriate credentials, a backend server for API proxy functionality, and a modern web browser with ES6 support.

Core Components

The Fastlane integration consists of three main JavaScript files: fastlaneSdkComponent.js for SDK initialization and client token management, fastlane.js for main integration logic and UI handling, and fastlane.css for basic styling of the checkout experience.

HTML Structure Requirements

Your HTML must include specific elements for the email form, payment containers, shipping display, order submission, and card testing information with proper IDs for JavaScript targeting.

1<!-- Email form -->
2<form id="email-form">
3  <input type="email" id="email-input" />
4  <div id="watermark-container"></div>
5  <button id="email-submit-button">Submit</button>
6</form>
7
8<!-- Payment containers -->
9<div id="card-container"></div>
10<div id="payment-container"></div>
11
12<!-- Shipping display -->
13<div id="shipping-display-container" hidden></div>
14<button id="change-shipping-button" hidden>Change Shipping Address</button>
15
16<!-- Order submission -->
17<button id="submit-button" hidden>Submit Order</button>
18
19<!-- Card testing info -->
20<p id="card-testing-info" hidden>
21  For more info on testing cards with PayPal, see
22  <a href="https://developer.paypal.com/tools/sandbox/card-testing/">
23    https://developer.paypal.com/tools/sandbox/card-testing/
24  </a>
25</p>

Load PayPal v6 Web SDK

Include the PayPal SDK script in your HTML to enable Fastlane functionality.

1<script
2  async
3  onload="onPayPalLoaded()"
4  src="https://www.sandbox.paypal.com/web-sdk/v6/core"
5></script>

Initialize SDK and Fastlane

Set up the PayPal SDK instance and create the Fastlane component with proper configuration including client token, page type, and metadata ID.

1async function onPayPalLoaded() {
2  const clientToken = await getBrowserSafeClientToken();
3
4  const sdkInstance = await window.paypal.createInstance({
5    clientToken,
6    pageType: "product-details",
7    clientMetadataId: crypto.randomUUID(),
8    components: ["fastlane"],
9  });
10
11  fastlane = await sdkInstance.createFastlane();
12  setupFastlaneSdk();
13}

Set Up Email Lookup Flow

The email lookup process determines whether a user is a Fastlane member and routes them to the appropriate checkout experience based on their authentication status.

1async function setupFastlaneSdk() {
2  fastlane.setLocale("en_us");
3
4  // Render Fastlane watermark
5  const fastlaneWatermark = await fastlane.FastlaneWatermarkComponent({
6    includeAdditionalInfo: true,
7  });
8  fastlaneWatermark.render("#watermark-container");
9
10  // Handle email submission
11  const emailSubmitButton = document.getElementById("email-submit-button");
12  emailSubmitButton.addEventListener("click", async (e) => {
13    e.preventDefault();
14
15    const { customerContextId } = await fastlane.identity.lookupCustomerByEmail(
16      emailInput.value,
17    );
18
19    let shouldRenderFastlaneMemberExperience = false;
20    let profileData;
21    
22    if (customerContextId) {
23      const response = await fastlane.identity.triggerAuthenticationFlow(customerContextId);
24
25      if (response.authenticationState === "succeeded") {
26        shouldRenderFastlaneMemberExperience = true;
27        profileData = response.profileData;
28      }
29    }
30
31    // Route to appropriate experience
32    if (shouldRenderFastlaneMemberExperience) {
33      renderFastlaneMemberExperience(profileData);
34    } else {
35      renderFastlaneGuestExperience();
36    }
37  });
38}

Handle Member Experience

For authenticated Fastlane members with saved data, display their shipping address and allow them to change it if needed, then render the payment component with pre-populated information.

1async function renderFastlaneMemberExperience(profileData) {
2  if (profileData.shippingAddress) {
3    setShippingAddressDisplay(profileData.shippingAddress);
4
5    // Allow address changes
6    const changeAddressButton = document.getElementById("change-shipping-button");
7    changeAddressButton.addEventListener("click", async () => {
8      const { selectedAddress, selectionChanged } = 
9        await fastlane.profile.showShippingAddressSelector();
10
11      if (selectionChanged) {
12        profileData.shippingAddress = selectedAddress;
13        setShippingAddressDisplay(profileData.shippingAddress);
14      }
15    });
16
17    // Render payment component with shipping address
18    const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
19      options: {},
20      shippingAddress: profileData.shippingAddress,
21    });
22
23    fastlanePaymentComponent.render("#payment-container");
24  }
25}

Handle Guest Experience

For new users or those not authenticated, render the full payment component that allows complete card entry and billing information input.

1async function renderFastlaneGuestExperience() {
2  const cardTestingInfo = document.getElementById("card-testing-info");
3  cardTestingInfo.removeAttribute("hidden");
4
5  const FastlanePaymentComponent = await fastlane.FastlanePaymentComponent({});
6  await FastlanePaymentComponent.render("#card-container");
7}

Process Payment

Generate a payment token from the Fastlane component and create an order through your backend API with the proper request structure and headers.

1// Get payment token
2const { id } = await fastlanePaymentComponent.getPaymentToken();
3
4// Create order via backend API
5async function createOrder(paymentToken) {
6  const response = await fetch("/paypal-api/checkout/orders/create", {
7    method: "POST",
8    headers: {
9      "Content-Type": "application/json",
10      "PayPal-Request-Id": Date.now().toString(),
11    },
12    body: JSON.stringify({
13      paymentSource: {
14        card: {
15          singleUseToken: paymentToken,
16        },
17      },
18      purchaseUnits: [
19        {
20          amount: {
21            currencyCode: "USD",
22            value: "10.00",
23            breakdown: {
24              itemTotal: {
25                currencyCode: "USD",
26                value: "10.00",
27              },
28            },
29          },
30        },
31      ],
32      intent: "CAPTURE",
33    }),
34  });
35  
36  return await response.json();
37}

Client Token Endpoint

Your backend must provide a GET endpoint at /paypal-api/auth/browser-safe-client-token that returns a client token for SDK initialization.

1// Backend endpoint response format
2{
3  "accessToken": "your-client-token"
4}

Order Creation Endpoint

Your backend must provide a POST endpoint at /paypal-api/checkout/orders/create that creates PayPal orders using the payment token with proper headers including Content-Type and PayPal-Request-Id.

1// Need BE example

Error Handling

The integration includes basic error handling where failed authentication falls back to guest experience, order creation errors display user-friendly messages, and console logging is available for debugging purposes.

Testing Environment

Use PayPal's sandbox environment with test cards available at the PayPal developer tools, requiring PayPal sandbox credentials in your backend configuration, and testing both member and guest checkout flows.

Running the Sample

Follow this link to our public examples repo where you can run Fastlane locally.