Fastlane for PayPal Complete Payments

Note: Fastlane is a limited-release solution. Features may change when the release becomes generally available. While you can integrate Fastlane in sandbox today, you must be part of the early adopter program in order to use Fastlane until our GA release.

Purpose

This integration guide specifies how a partner or merchant can integrate Fastlane, an accelerated checkout product on the PayPal Complete Payments Platform, into their site.

Scope

Fastlane is an accelerated checkout solution targeted at guest payers to your store. If the payer already has a store account and has logged into it, continue to render your pre-existing checkout flow for store logged-in members. For store guest members, render the following integration flow.

Integration flow

The following diagram depicts the integration changes required to enable Fastlane.

1. Set up server side

Take the following steps to set up Fastlane on the server side.

Generate server-side client token

To instantiate the JavaScript SDK and Fastlane components:

1. Generate an SDK token through a server-side call.
2. Pass the token into the SDK.

Important To protect yourself against cross-site scripting attacks, send domains in a comma-separated format in the request to generate a client token. You must provide the root domain name; for example, example.com. Specifying subdomains, wildcards or HTTP protocols such as https:// will result in an error.

Request the token to initialize 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=sdk_token' \
6 -d 'intent=sdk_init' \
7 -d 'domains[]=/merchant.com,/merchant2.com'

Sample response

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}

2. Set up client side

Take the following steps to integrate on the client side.

Initialize SDK and Fastlane

Fastlane is initialized through a call to paypal.fastlane and passed a configuration object. Pass the device data when initializing Fastlane to prevent fraudulent access to Fastlane profiles.

First, 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  data-client-metadata-id="<CM_ID>">
5</script>

The new component for Fastlane is called fastlane. The following fields are required to initialize the SDK:

• client-id

• data-sdk-client-token

• data-client-metadata-id

Next, initialize the Fastlane component:

1// instantiates the Fastlane module
2const fastlane = await window.paypal.Fastlane({
3  // For more details about available options parameters, see the Reference section.
4});
5// sets the SDK to run in sandbox mode
6window.localStorage.setItem("fastlaneEnv", "sandbox");
7// Specifying the locale if necessary
8fastlane.setLocale('en_us');

Specify locale

After you initialize the Fastlane component, you can specify the locales where the Fastlane components render.

Fastlane supports the following languages:

• en_us (default) - US English
• es_us - Spanish
• fr_us - French
• zh_us - Chinese

Capture email address

The first step of the checkout flow involves gathering the email address from the payer. Given that this email address will be shared with PayPal, we recommend that you notify the payer accordingly. Make sure to display the Fastlane watermark along with an information icon beneath the email address input field.

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

Note PayPal is a data controller and a key business partner for Fastlane services. As such, payer email addresses are shared with PayPal. Inform payers about PayPal by using our SDK to display the "Powered by Fastlane" logo and an informational tooltip. If you have any inquiries about Fastlane or data protection legislation, seek guidance from your legal advisors.

3. Look up and authenticate payer

After collecting the payer's email address, call identity.lookupCustomerByEmail(email). This method looks up an email address to determine if the payer is a Fastlane or PayPal member.

Fastlane members need to authenticate themselves before you can get their profile information. They are presented with a screen to enter a one-time password sent to their registered mobile number.

You can use the following sample to trigger the authentication flow and handle the response.

Note: The following sample sets a variable called renderFastlaneMemberExperience to simplify the conditional logic. Feel free to use any method to handle this in your implementation.

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

The triggerAuthenticationFlow() method returns an AuthenticatedCustomerResult object. You can use the value of the authenticationState property in this object to determine if the payer has authenticated themselves. The returned object also contains the payer’s default shipping address and card.

If a Fastlane member fails or declines to authenticate, render the same experience that you would for a guest payer.

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

4. Render shipping address

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

Render address for Fastlane member

After the Fastlane member is authenticated, their shipping information is returned in the profileData.shippingAddress object. Use that returned data to render shipping information on your checkout page.

A Fastlane member may have multiple shipping addresses in their profile or want to enter a new address. Render a button to change the address.

Call the profile.showShippingAddressSelector() method when the payer selects the changeAddressButton. This gives the payer a list of addresses to pick from or enter a new address. When the payer makes a selection, the method returns the selected address. If they cancel without changing the selection, selectionChanged is set to false, and selectedAddress is set to null.

To restrict shipping to specific countries or regions, specify the shippingAddressOptions parameter when initializing the Fastlane component. Refer to Reference types for more information.

If PayPal doesn't provide a shipping address for a Fastlane member, you'll need to render your own shipping address form.

When displaying a shipping address from a payer’s Fastlane profile, you must display the Fastlane watermark without the info icon below the address as shown previously. For details on how to render the watermark, refer to Render the Fastlane watermark.

Note: Fastlane requires a US billing address, but the shipping address can be anywhere your site ships. If the payer selects another address from the list, or adds a new address, send the address in the server-side v2/orders request.

Render address for guest users

Guest users don't have an address in Fastlane. You'll need to render your existing shipping form to collect shipping information and pass it to PayPal upon checkout. This ensures that if a payer creates a Fastlane profile, the profile is created with the payer's shipping address.

JavaScript sample

You can use the following code as a reference to implement the shipping address for both user types.

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

5. Accept payment

Fastlane offers two different integration patterns to accept payments.

Select component or flexible integration

The component integration requires minimal integration effort from your end. Component is our recommended integration path and automatically handles certain integration items without the need for additional logic. However, if you require finer control of the user interface and styling, we recommend the flexible integration.

The flexible integration requires you to handle the billing address on your own. If you use the flexible integration, you'll need to:

• Render the card menu and the watermark.
• Build conditional logic to determine when to show card fields.
• Render form fields to collect the billing address and pass it to the transaction.

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

Note: Your checkout needs to collect a billing address and cardholder name to use Fastlane. When calling the getPaymentToken() method, pass the billing address as shown previously.

If you have enabled the Cardholder Name field, the cardholder name will be collected automatically. If you have disabled it, you will need to send it in the getPaymentToken() method.

6. Create order

On your server, create an order by calling the Orders API. Pass the single-use token, item details, and shipping address. Provide detailed item descriptions and product images for each item the payer purchased.

Providing detailed item descriptions and product images has the following advantages:

• Creates the ideal user experience for email communications with the payer
• Streamlines potential dispute resolutions.

For partners or platforms, use the PayPal-Partner-Attribution-ID header and the BN-CODE to attribute transactions to the appropriate partner accounts.

One-shot 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}'

Important: If the payer is picking up the item from a store, modify the shipping type in the purchase_units.shipping object to PICKUP_IN_STORE. This ensures that payer profiles aren't created with the store address as their shipping address.

Headers for partner merchants

If you are integrating on behalf of a partner merchant, you'll need the following additional headers:

1-H "PayPal-Partner-Attribution-ID: BN-CODE"\
2 -H "PayPal-Auth-Assertion: AUTH-ASSERTION-TOKEN"

Save Fastlane payment tokens

To save the paymentToken from the Fastlane SDK, use the store_in_vault attribute in the v2/orders request on your server.

Render the Fastlane watermark

You can render the Fastlane watermark with or without an info icon.

The image tag in the watermark container div allows the watermark to render instantly. The mouse-over tooltip functionality displays when the watermark component loads.

1<!-- Add a div where the watermark will be rendered -->
2<div id="watermark-container"><img src="https://www.paypalobjects.com/fastlane-v1/assets/fastlane-with-tooltip_en_sm_light.0808.svg" /></div>

Preload watermark assets to optimize Fastlane

For a better payer experience, we recommend preloading the watermark asset by adding the following code to the <head> section of the page. Note that this is an optional but recommended step.

1<link rel="preload" href="https://www.paypalobjects.com/fastlane-v1/assets/fastlane-with-tooltip_en_sm_light.0808.svg" as="image" type="image/avif" />
2<link rel="preload" href="https://www.paypalobjects.com/fastlane-v1/assets/fastlane_en_sm_light.0296.svg" as="image" type="image/avif" />

Error Conditions

Disablement Flows

If Fastlane has been disabled from within the PayPal dashboard, the Fastlane client SDKs are built so that there will be no interruption to your buyers. This means the SDK will revert to the guest experience without the ability for a buyer to opt-in to creating a Fastlane profile. Card fields will work as expected and processing guest transactions will continue to function.

In the event of Fastlane being disabled from within the PayPal dashboard, note that the following methods will return undefined.

• identity.triggerAuthenticationFlow()

• profile.showShippingAddressSelector()

• profile.showCardSelector()

Test your integration

To test your integration in the sandbox environment, set the following local storage variables before initializing the Fastlane component.

1window.localStorage.setItem("axoEnv", "sandbox");

After integrating Fastlane on your website, launch the site and use the following values to test the integration for the 3 user types:

Test guest payer flow

• Provide an email address that is new and not associated with a sandbox Fastlane account.
• Go through the checkout process using one of the following test card numbers. Be sure that the opt-in toggle is in the "on" state. You can enter any valid phone number. No SMS is sent in sandbox mode.
• Upon completing the transaction, a Fastlane profile is created that can be used for testing subsequent transactions as a Fastlane member.

Test Fastlane member flow

• Go through the previous steps and register a new Fastlane account. Be sure to remember the email address used when you created the account so that you can use it for additional testing.
• When the authentication modal appears and you are prompted for a one-time password (OTP) use 111111 to simulate authentication. Use any other 6-digit number to simulate failed authentication.
• Make sure that you test the payer's ability to update shipping addresses and cards associated with their profile.

PayPal members without a Fastlane profile do not require any additional handling within your integration. 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.
• Trigger 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 buyer selects yes, we return profileData exactly as we would for a Fastlane member.
• If the buyer closes the dialog, we return an empty profileData object and you handle the buyer as any Fastlane guest.

Use test card numbers

Use the following mock card numbers to test transactions.

Reference types

Note: You may see references to Connect in the SDK. These are artifacts from a deprecated integration path. Only use methods and components named Fastlane.

Fastlane window configuration parameters

window.paypal.Fastlane(options); configuration parameters:

1interface FastlaneOptions {
2  shippingAddressOptions: AddressOptions,
3  cardOptions: CardOptions,
4  styles: StyleOptions
5}
6
7/*
8 * To restrict the use of Fastlane to specific countries or regions, set
9 * allowedLocations to an array containing the countries or regions where Fastlane
10 * should be allowed.
11 *
12 * To allow all regions within a particular country, specify the country's
13 * ISO 3166-1 alpha-2 country code only.
14 *
15 * To allow only specific regions in a country, specify the country's
16 * ISO 3166-1 alpha-2 country code, followed by a colon (":"), followed by the
17 * name of the region.
18 *
19 * Examples:
20 *   - [ "US" ] = Allow all regions within the United States
21 *   - [ "US:CA", "US:AZ" ] = Allow in California and Arizona, but nowhere else
22 *   - [ "US:CA", "US:AZ", "FR" ] = Allow in California, Arizona, and France,
23 *       but nowhere else
24 */
25
26interface AddressOptions {
27  // default: empty array = all locations allowed
28  allowedLocations: [AddressLocationEnum];
29}
30
31Enum AddressLocationEnum {
32  {ISO-country-code}
33  {ISO-country-code}:{ISO-region-code}
34}
35
36interface CardOptions {
37  // default: empty array = all brands allowed
38  allowedBrands: [CardBrandEnum];
39}
40
41Enum CardBrandEnum {
42  VISA
43  MASTERCARD
44  AMEX
45  DINERS
46  DISCOVER
47  JCB
48  CHINA_UNION_PAY
49  MAESTRO
50  ELO
51  MIR
52  HIPER
53  HIPERCARD
54}

1type create = (options: FastlaneOptions) => Fastlane;

Fastlane namespace

This is returned as the result of calling fastlane.create({\...}).

1interface Fastlane {
2  identity {
3    lookupCustomerByEmail: (email: string) => LookupCustomerResult,
4    triggerAuthenticationFlow: (customerContextId: string, options: AuthenticationFlowOptions) => AuthenticatedCustomerResult
5  }
6
7  profile {
8    showShippingAddressSelector: () => ShowShippingAddressSelectorResult,
9    showCardSelector: () => ShowCardSelectorResult,
10  }
11
12  setLocale: (locale: string) => void,  // options: en_us, es_us, fr_us, zh_us
13
14  FastlaneCardComponent: (options: FastlaneCardComponentOptions) => FastlaneCardComponent,
15  FastlanePaymentComponent: (options: FastlanePaymentComponentOptions) => FastlanePaymentComponent,
16  FastlaneWatermarkComponent: (options: FastlaneWatermarkOptions) => FastlaneWatermarkComponent
17}

LookupCustomerResult

The LookupCustomerResult object type is returned from the identity.lookupCustomerByEmail(email) method.

1interface LookupCustomerResult {
2  customerContextId: string
3}

Fastlane watermark component

1interface FastlaneWatermarkOptions {
2  includeAdditionalInfo: boolean
3}
4
5interface FastlaneWatermark {
6  render: (container) => null
7}

AuthenticatedCustomerResult

The AuthenticatedCustomerResult object type is returned from the identity.triggerAuthenticationFlow() call.

1interface AuthenticatedCustomerResult {
2  authenticationState: 'succeeded'|'failed'|'canceled'|'not_found';
3  profileData: ProfileData;
4}
5
6interface ProfileData {
7  name: Name;
8  shippingAddress: Shipping;
9  card: PaymentToken;
10}
11
12interface Name = {
13  firstName: string;
14  lastName: string;
15  fullName: string;
16};
17
18interface Phone = {
19  nationalNumber: string;
20  countryCode: string;
21};
22
23interface Address = {
24  addressLine1: string,
25  addressLine2: string,
26  adminArea1: string,
27  adminArea2: string;
28  postalCode: string,
29  countryCode: string
30  phone: Phone;
31};
32
33interface Shipping = {
34  name: Name;
35  phone: Phone;
36  address: Address;
37  companyName: string;
38}
39
40interface BillingAddress = Address;
41
42interface PaymentToken {
43  id: string; // This is the paymentToken
44  paymentSource: PaymentSource;
45}
46
47interface PaymentSource {
48  card: CardPaymentSource;
49}
50
51interface CardPaymentSource {
52  brand: string;
53  expiry: string; // "YYYY-MM"
54  lastDigits: string; // "1111"
55  name: string;
56  billingAddress: Address;
57}

Profile method reference types

1interface ShowShippingAddressSelectorResult {
2  selectionChanged: boolean;
3  selectedAddress: Address;
4}
5
6interface ShowCardSelectorResult {
7  selectionChanged: boolean;
8  selectedCard: PaymentToken;
9}

Fastlane card component

The FastlaneCardComponent is a subset of the Hosted Card Fields interface.

Use the following code to create an instance of the FastlaneCardComponent:

1const fastlaneCardComponent = await fastlane.FastlaneCardComponent({...});
2await fastlaneCardComponent.render("#card-container")

Fastlane card component reference types

1type FastlaneCardComponent = (options: FastlaneCardComponentOptions) => FastlaneCardComponent;
2
3interface FastlaneCardComponent {
4  render: (container) => FastlaneCardComponent;
5  getPaymentToken: async (options: PaymentTokenOptions) => PaymentToken;
6}
7
8interface FastlaneCardComponentOptions {
9  styles: StyleOptions;
10  fields: {Field};
11}
12
13interface Field {
14  placeholder: string;
15  prefill: string;
16}
17
18interface PaymentTokenOptions {
19  billingAddress: Address;
20}

Fastlane payment component

Create a FastlanePaymentComponent with the following code:

1const fastlanePaymentComponent = await fastlane.FastlaneEmailComponent({ ... });
2
3fastlanePaymentComponent.render("#payment-container");

Payment component reference types

1type FastlanePaymentComponent = (options: FastlanePaymentComponentOptions) => FastlanePaymentComponent;
2
3interface FastlanePaymentComponent {
4  render: (container) => FastlanePaymentComponent;
5  getPaymentToken: async () => PaymentToken;
6  setShippingAddress: (shippingAddress: Address) => void;
7}
8
9interface FastlanePaymentComponentOptions {
10  styles: StyleOptions;  
11  fields: {Field};
12  shippingAddress: Address;
13}
14
15interface Field {
16  placeholder: string;
17  prefill: string;
18}

Card field configurations

You can configure the card fields in the FastlaneCardFieldComponent or FastlanePaymentComponent when initializing the components.

1const styles: {};
2const fields: {
3    number: {
4      placeholder: "Enter your card number",
5    },
6    phoneNumber: {
7      prefill: "555-555-5555"
8    },
9    cardholderName: {
10      prefill: "John Doe",
11      enabled: true
12    }
13  }
14}
15
16const fastlaneCardComponent = fastlane.FastlaneCardComponent({
17  styles,
18  fields
19});
20
21fastlaneCardComponent.render(elem);
22
23const fastlanePaymentComponent = fastlane.FastlanePaymentComponent({
24  styles,
25  fields
26});/n
27fastlanePaymentComponent.render(elem);/n

Available fields

Style options and guidelines

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

1interface StyleOptions {
2  root: {
3    backgroundColor: string // default: #ffffff,
4    errorColor: string, // default: #C40B0B
5    fontFamily: string, // default: "PayPal Open"
6    textColorBase: string, // default: #222222
7    fontSizeBase: string, // default: 16px
8    padding: string, // default: 4 px
9    primaryColor: string // default #?
10  },
11  input: {
12    backgroundColor: string, // default #ffffff
13    borderRadius: string, // default: 0.25rem
14    borderColor: string, // default: #DCDCDC
15    borderWidth: string, // default: 1px
16    textColorBase: string, // default #222222
17    focusBorderColor: string, // default: #0021A3
18  },

Make checkout components accessible

When styling Fastlane components to match your checkout page, there are some guidelines you'll need to follow to provide an accessible and transparent experience to your payer.

• Ensure adequate contrast between the backgroundColor and textColor. All text, especially the legal text under the opt-in, is clear and legible. If the contrast ratio between the two variables is not 4.5:1, we will automatically set them to the default values in the following table.
• Ensure adequate contrast between the borderColor, which drives the consent toggle coloring, and the backgroundColor.

Important: All Fastlane integrations must conform to current WCAG levels A and AA. Be sure to comply with these standards when styling any Fastlane UI components.

The following is a list of how this interface applies to each of the Fastlane components:

Data priority

The following table lists the required data to create a Fastlane profile, how to pass the information, and which data takes priority.

FAQs

Will Fastlane work if I save a payer's payment method?

Yes, the paymentToken returned on the client can be saved to the vault when creating a transaction on your server. You can save a payment method only when using the store_in_vault attribute of the create order request.

We currently do not support the ability to save a buyer's card information prior to transacting.

How long is a payment token valid?

A paymentToken is valid for 3 hours from issuance.

What if the payer's shipping address is in a location that my site doesn't ship to?

When you initially call window.paypal.fastlane.create(), you can pass in a list of allowed locations using the addressOptions object. See reference types for details.

How should I handle cases where a payer navigates away from the checkout page to add or remove items?

It's best practice to call the triggerAuthenticationFlow() method every time the checkout page is reloaded. Internal logic within our SDK determines whether we require the payer to authenticate through a one-time password or restore the session. In either case, the method returns the authenticatedCustomerResult. This also includes a new paymentToken.

How can I test Fastlane outside the US?

Fastlane is only available to payers in the US. If you are outside the US, you must use a VPN to test payer flows.