A Faster Guest Checkout: How to Integrate Fastlane by PayPal

Welcome to our comprehensive integration guide for Fastlane by PayPal, the accelerated guest checkout solution on the PayPal Complete Payments platform (PPCP). We'll walk you through every step of integrating Fastlane, ensuring a smooth and efficient implementation that leverages the full power of PPCP.  

What is Fastlane by PayPal?

For merchants, Fastlane is an innovative guest checkout solution designed to streamline the purchasing process. With Fastlane, merchants can provide a seamless, efficient checkout experience, helping to drive higher sales.

Set up Fastlane on the Server Side  

Fastlane offers an efficient and streamlined approach to setting up accelerated checkout functionalities, helping to create swift and secure transactions for users. Perform the following steps to successfully configure Fastlane on the server side and be equipped to integrate express checkout seamlessly into your server environment:  To use the JavaScript SDK and Fastlane components, generate a server-side SDK token and pass it to the SDK.

For merchant transactions or third-party solutions, modify the code for requesting the token for SDK initialization by replacing CLIENT-ID, CLIENT-SECRET, and domains with your credentials and endpoints for secure authentication.

To initialize Fastlane, use the following script tag to include the SDK:

1<script>
2    src="https://www.paypal.com/sdk/js?Client-id=<CLIENT-ID>&components=buttons,fastlane"
3    data-sdk-client-token="<SDK_CLIENT_TOKEN>"
4</script>

Instantiate Fastlane with the following code:

1const fastlane = await window.paypal.Fastlane();
2window.localStorage.setItem("fastlaneEnv", "sandbox");
3fastlane.setLocale('en_us');  // Set locale if needed

Specify the locale for Fastlane (US English, Spanish, French, Chinese) and inform payers about email sharing by displaying a watermark and an information icon during the checkout process.

Refer to Render the Fastlane watermark for instructions on rendering the watermark component. 

Look up and Authenticate the Payer

After collecting the payer's email, check if they are a Fastlane or PayPal member. For Fastlane members, prompt them for a one-time password sent to their mobile. Use the following code sample to trigger authentication and handle responses.

1const { customerContextId } = await identity.lookupCustomerByEmail(document.getElementById("email").value);
2
3var renderFastlaneMemberExperience = false;
4
5if (customerContextId) {
6    // Email is associated with a Fastlane member or a PayPal member,
7    // send customerContextId to trigger the authentication flow.
8    const { authenticationState, profileData } = await identity.triggerAuthenticationFlow(customerContextId);
9
10    if (authenticationState === "succeeded") {
11        // Fastlane member successfully authenticated themselves
12        // profileData contains their profile details
13        renderFastlaneMemberExperience = true;
14
15        const name = profileData.name;
16        const shippingAddress = profileData.shippingAddress;
17        const card = profileData.card;
18    } else {
19        // Member failed or cancelled to authenticate. Treat them as a guest payer
20        renderFastlaneMemberExperience = false;
21    }
22} else {
23    // No profile found with this email address. This is a guest payer
24    renderFastlaneMemberExperience = false;
25}

Refer to Reference types for more information on what options can be passed to each function shown in the code sample.   

Render Shipping Address

The integration varies depending on the payer use case. The following table explains the different scenarios to implement:

For authenticated Fastlane members, use profileData.shippingAddress to display their shipping details and provide options to update or select addresses. For guest users, render a shipping form to collect and pass shipping information to PayPal.

Accept Payments

Fastlane offers two integration options:   

Quick Start: Simple and easy, with minimal setup and automatic management of integration tasks. 

Flexible Integration: Provides more control over UI and design, requiring you to manage billing details, card menus, conditional fields, and user flows.     

Next, we'll detail how to integrate Fastlane's Quick Start and Flexible Integration options into your app, offering guidance for both simple and advanced payment processing. Stay tuned for comprehensive instructions. 

Component Integration

The FastlanePaymentComponent automatically displays the selected card, a link to change cards, card fields for guest users or members without a saved card, and billing address fields.

Flexible Integration

The flexible integration varies by user type: 

• Fastlane members with a stored card: Display the selected card, Fastlane watermark, and a change card button. 
• Members without a card, unsupported cards, or guests: Use FastlaneCardComponent for new card info and a form for billing address.

Create Transaction with Orders API

To process an order, use the Orders API to submit a single-use token, item details, and shipping address, including descriptions and images for each item. This helps improve the user experience and aids in dispute resolution.   

One click checkout through Orders API with shipping

1curl -v -k -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'PayPal-Request-Id: UNIQUE_ID' \
3-H 'Authorization: Bearer PAYPAL_ACCESS_TOKEN' \
4-H 'Content-Type: application/json' \
5-H 'PayPal-Client-Metadata-Id: YOUR_CMID' \
6-d '{
7  "intent": "CAPTURE",
8  "payment_source": {
9    "card": {
10      "single_use_token": "1h371660pr490622k" // Payment token from the client
11    }
12  },
13  "purchase_units": [
14    {
15      "amount": {
16        "currency_code": "USD",
17        "value": "50.00",
18        "breakdown": {
19          "item_total": {
20            "currency_code": "USD",
21            "value": "40.00"
22          },
23          "shipping": {
24            "currency_code": "USD",
25            "value": "10.00"
26          }
27        }
28      },
29      "items": [
30        {
31          "name": "Coffee",
32          "description": "1 pound of coffee beans",
33          "sku": "sku03",
34          "unit_amount": {
35            "currency_code": "USD",
36            "value": "40.00"
37          },
38          "quantity": "1",
39          "category": "PHYSICAL_GOODS",
40          "image_url": "https://example.com/static/images/items/1/coffee_beans.jpg",
41          "url": "https://example.com/items/1/coffee_beans",
42          "upc": {
43            "type": "UPC-A",
44            "code": "987654321015"
45          }
46        }
47      ],
48      "shipping": {
49        "type": "SHIPPING",
50        "name": {
51          "full_name": "Firstname Lastname"
52        },
53        "address": {
54          "address_line_1": "123 Fake St.",
55          "admin_area_2": "Los Angeles",
56          "admin_area_1": "CA", // Must be sent in 2-letter format
57          "postal_code": "90049",
58          "country_code": "US"
59        },
60        "phone_number": {
61          "country_code": "1",
62          "national_number": "5555555555"
63        }
64      }
65    }
66  ]
67}'

Test your Integration

After integrating Fastlane, test with these steps for each user type: 

Guest: Use a new email, test with provided card numbers, and ensure the opt-in toggle is on. A Fastlane profile will be created for future testing. 

Fastlane Member: Register a new account, use 111111 for successful OTP and any 6-digit number for failed OTP. Test address and card updates. 

Card Testing: Use the mock card numbers provided for transactions.

Fastlane Integration Best Practices  

Buyer Experience

Aim to display the Branded PayPal button prominently, ideally on the cart page or near the Fastlane email field, to give consumers the option to use PayPal and enhance the guest checkout experience.

Email address entry should always be the first step.

Always place the email address field first in the checkout process, as Fastlane uses it to retrieve shipping and payment info. This avoids confusion and applies to both Fastlane UI components and custom implementations.

Use the Fastlane watermark.

The Fastlane watermark below any merchant-rendered fields for full consumer transparency. The watermark contains a link where a buyer can go to see the Fastlane ToS.

Streamline the process

After a Fastlane member authenticates and their profile information is received, hide other payment methods under a single link once Fastlane payment details are displayed.

After a buyer completes the OTP challenge and chooses Fastlane, keep the UI minimalistic to boost conversion, but ensure other payment options remain accessible in case they change their mind.  

Registered Fastlane Member Flows

After a Fastlane member authenticates, direct them to the order review page, automatically select the cheapest shipping option, and provide "change" buttons for updating the shipping address and card details using `showAddressSelector()` and `showCardSelector()`. Ensure any other specific use cases, like adding a gift message, are addressed on the relevant page.

Integration

Load the Fastlane SDK on the checkout page’s onload event to help avoid conversion issues. Always send shipping and billing addresses server-side, especially when changes are made. Call `triggerAuthenticationFlow()` on page reload to manage authentication and get a new nonce. Provide options for Fastlane members to update their credentials by rendering change buttons that call `profile.showShippingAddressSelector() ` or `profile.showCardSelector() ` to allow editing. 

Styling

Merchants should ensure ADA compliance on their checkout page, with sufficient contrast between background and text colors, and between border colors and backgrounds for clear legibility of text and UI components. 

Style Options and Guidelines

Colors can be any value that CSS allows including hex values, rgb, rgba, and color names.

General Design Guidance

When styling Fastlane components, ensure sufficient contrast between background and text colors, and between border colors and backgrounds, to enhance accessibility and clarity. This will improve the checkout experience for Fastlane members.

Error Conditions

Visit the product developer integration portal and explore how effortlessly you can design an accelerated checkout experience. For how the new product integration experience can enable faster and more efficient integrations read this blog.