Integrate Fastlane

Fastlane is PayPal’s quick guest checkout solution. It securely saves and retrieves payment and shipping information for Fastlane members. Fastlane members enter their email and receive prefilled checkout forms.

Availability

Fastlane is available:

• In the US only.
• For both desktop and mobile web.

Prerequisites

• If you're processing payments on legacy PayPal APIs, you'll need to upgrade to Orders v2.
• Make sure you've completed the steps in Getting started.
• You must process card payments with PayPal.
• You must present PayPal as a payment option alongside a field for Fastlane email collection. Email collection is the first step in Fastlane checkout.
• You must collect a billing address during checkout.

Add PayPal to your Content Security Policy and initialize the SDK from your server.

Content Security Policy (CSP) is a web browser feature that helps prevent cross-site scripting and other attacks. CSP restricts the sources used to load resources on your page. This allows you to maintain better control over potentially malicious code.

In your policy, set frame-src to *.paypal.com.

To initialize the PayPal JS SDK and Fastlane components, generate a client token through a server-side call and then pass the token into the SDK.

1curl -s -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \
2 -u CLIENT_ID:CLIENT_SECRET \
3 -H "Content-Type: application/x-www-form-urlencoded" \
4 -d "grant_type=client_credentials" \
5 -d "response_type=client_token" \
6 -d "intent=sdk_init" \
7 -d "domains[]=example.com,example2.com"

Copy the sample code and modify as follows:

• Get your client ID and secret from your Developer Dashboard.
• Replace CLIENT_ID with your client ID.
• Replace CLIENT_SECRET with your client secret.
• Replace example.com,example2.com with your own domains. Provide the root domain name only.
  • No subdomains such as sub.example.com.
  • No wildcard characters such as *.example.com.
  • No protocols such as http or https.

1{
2  "access_token" : "eyJraW...",
3  "app_id": "APP-80W2...",
4  "expires_in": 32400,
5  "nonce": "2024-01...",
6  "scope": "...",
7  "token_type": "Bearer"
8}

1. Integrate front-end

Set up your client side to integrate Fastlane.

Initialize the SDK through the following script tag on your HTML page.

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>

Fastlane is initialized with a call to paypal.Fastlane. You must pass a configuration object during initialization.

The following fields are required to initialize the SDK:

• client-id: The client ID of your application
• data-sdk-client-token from setting up your server.

1// instantiates the Fastlane module
2const fastlane = await window.paypal.Fastlane({ }); 
3
4// Convenience parameters for calling later on
5const { identity,
6  profile,
7  FastlanePaymentComponent,
8  FastlaneWatermarkComponent,
9 } = fastlane;

You can specify the language in which the Fastlane components are rendered. After you initialize the Fastlane component, you can set the locale.

1fastlane.setLocale("en_us"); // en_us is the default value

Fastlane supports the following languages:

• en_us - English, default
• es_us - Spanish
• fr_us - French
• zh_us - Mandarin

You'll need to render your own email field to capture the payer's email address.

Because the email address is shared with PayPal, it is crucial to inform the payer. We recommend displaying the Fastlane watermark below the email field.

After collecting the email address, PayPal determines whether the email is associated with a Fastlane profile or if it belongs to a PayPal member. Use the following code snippet to look up the customer's email.

1const {
2  customerContextId
3} = await identity.lookupCustomerByEmail(document.getElementById("email").value);

If the user is identified with a Fastlane profile, they need to authenticate before Fastlane retrieves their saved payment and address information. The user is presented with a screen to authenticate themselves by entering a one-time password sent to their registered mobile number.

You can use the following code to trigger the authentication flow and handle the response:

1const {
2  customerContextId
3} = await identity.lookupCustomerByEmail(document.getElementById("email").value); 
4
5//this variable  will turn to True if user authenticates successfully with OTP
6//will remain False by default
7
8 let renderFastlaneMemberExperience = false; 
9
10if (customerContextId) {
11  // Email is associated with a Fastlane member or a PayPal member,
12  // send customerContextId to trigger the authentication flow.
13  const {
14    authenticationState,
15    profileData
16  } = await identity.triggerAuthenticationFlow(customerContextId); 
17
18  if (authenticationState === "succeeded") {
19    // Fastlane member successfully authenticated themselves
20    // profileData contains their profile details 
21
22    renderFastlaneMemberExperience = true; 
23
24    const name = profileData.name;
25    const shippingAddress = profileData.shippingAddress;
26    const card = profileData.card;
27} else {
28  // Member failed or canceled authentication. Treat them as a guest payer
29  renderFastlaneMemberExperience = false;
30  }
31} else {
32  // No profile found with this email address. This is a guest payer
33  renderFastlaneMemberExperience = false;
34}

The triggerAuthenticationFlow() method returns an AuthenticatedCustomerResult object. Use the authenticationState property in the AuthenticatedCustomerResult object to check if the payer has been authenticated.

On authentication:

• The Fastlane member's card details and default shipping address are returned with the profileData object contents.
• The renderFastlaneMemberExperience is set to True.

If a user fails or declines to authenticate, render the same experience as you would for a guest payer.

This step is not required for:

• Fastlane members without a shipping address.
• Fastlane members with a shipping address in a region you don't support.
• Guest payers.

For Fastlane members with a shipping address, you'll need to render:

• Shipping address returned from profile data on authentication.
• Fastlane watermark.
• Fastlane by PayPal logo.
• Change address button that invokes showShippingAddressSelector(). This helps the payer change or add a new address as needed.

If the user addes a new address to their Fastlane profile, send the new address in the Orders v2 server-side request.

The following code renders a shipping address for Fastlane members and guest users:

1if (renderFastlaneMemberExperience) { 
2
3  if (profileData.shippingAddress) {
4    // render shipping address from the profile
5    const changeAddressButton = document.getElementById("your-change-address-button");
6    changeAddressButton.addEventListener("click", async () => {
7      const {
8        selectedAddress,
9        selectionChanged
10      } = await profile.showShippingAddressSelector();
11      if (selectionChanged) {
12        // selectedAddress contains the new address
13      } else {
14        // selection modal was dismissed without selection
15      }
16    });
17  } else {
18    // render your shipping address form
19  }
20} else {
21  // render your shipping address form
22}

Fastlane offers two different integration patterns to accept payments; quick start and flexible.

1<!-- Div container for the Payment Component -->
2<div id="payment-container"></div>
3<!-- Submit Button -->
4<button id="submit-button">Submit Order</button>

1const shippingAddress = {
2  firstName: "Jen",
3  lastName: "Smith",
4  company: "Braintree",
5  streetAddress: "1 E 1st St",
6  extendedAddress: "5th Floor",
7  locality: "Bartlett",
8  region: "IL", // must be sent in 2-letter format
9  postalCode: "60103",
10  countryCodeAlpha2: "US",
11  phoneNumber: "14155551212"
12} 
13
14const options = {
15  fields: {
16    phoneNumber: {
17      // Example of how to prefill the phone number field in the FastlanePaymentComponent
18      prefill: "4026607986"
19    }
20  },
21  styles: {
22    root: {   //specify styles here
23      backgroundColorPrimary: "#ffffff"
24    }
25  }
26}; 
27
28const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
29    options,
30    shippingAddress
31  });
32  await fastlanePaymentComponent.render("#payment-container"); 
33
34// event listener when the user clicks to place the order
35const submitButton = document.getElementById("submit-button");
36submitButton.addEventListener("click", async ()=> {
37  const { id } = await fastlanePaymentComponent.getPaymentToken(); 
38
39  // Send the paymentToken and previously captured device data to server
40  // to complete checkout
41});

2. Integrate back end

On your server, create an order by calling the Orders API and passing the single-use token, along with the item details and the shipping address.

Provide detailed item descriptions and product images for each item to:

• Create a better user experience for email communications.
• Streamline any potential dispute resolution.

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: <CM_ID>' \
6 -d '{
7  "intent": "CAPTURE",
8  "payment_source": {
9    "card": {
10      "single_use_token": "1h371660pr490622k" //paymentToken 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 lb Kona Island 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/kona_coffee_beans.jpg",
41          "url": "https://example.com/items/1/kona_coffee_beans",
42          "upc": {
43            "type": "UPC-A",
44            "code": "987654321015"
45          }
46        }
47      ],
48      "shipping": {
49        "type": "SHIPPING",
50        "name": {
51          "full_name": "Lawrence David"
52        },
53        "address": {
54          "address_line_1": "585 Moreno Ave",
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}'

Store pick-up: If the buyer is picking up the item from a storefront, modify the shipping type parameter in the call and ensure the shipping method is set to PICKUP_IN_STORE. This ensures that buyer profiles aren't created with the address of your store as their shipping address.

Vaulting: If you want to save the paymentToken returned by the Fastlane SDK at the time of transaction, you can do so only when using the store_in_vault attribute in the request to /v2/orders on your server. This returns a vault ID, which can be saved and used for future transaction. See the Orders v2 documentation for more details.

3. Test integration

You'll need to test your integration for guest payers and Fastlane members, with and without the consent toggle on. Testing varies depending on whether your integration is quick start or flexible.

PayPal members who choose not to save their profile are treated as guest users.

PayPal members who choose to save their profile are treated as returning Fastlane members for future transactions.

PayPal members do not require any additional handling within your integration because our client SDK handles this use case for you in the following ways:

• After performing the lookupCustomerByEmail method, we return a customerContextId as if this were a Fastlane member.
• When you call the triggerAuthenticationFlow method, our SDK displays a call to action to the buyer explaining that they can create a Fastlane profile populated with information from their PayPal account with one click.
• If the consumer clicks yes, PayPal returns profileData exactly as we would for a Fastlane member.
• If the consumer closes the dialog, PayPal returns an empty profileData object and you would handle this as you would any Fastlane guest member.

Use the following test card numbers for sandbox transactions:

4. Go live

If you have fulfilled the requirements for accepting card payments via Fastlane for your business account, review Move your app to production to test and go live.

If this is your first time testing in a live environment, follow these steps:

• Log into the PayPal Developer Dashboard with your PayPal business account.
• Complete production onboarding so you can process card payments with your live PayPal business account.

Request Advanced Credit and Debit Card Payments for your business account if you are not using cards currently with PayPal. Fastlane will be enabled along with the Advanced Credit and Debit Card payments processing.