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

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.

1. Integrate front-end

Set up your client side to integrate Fastlane.

1. Initialize SDK and Fastlane

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

<script>
  src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>>&components=buttons,fastlane"
  data-sdk-client-token="<SDK_CLIENT_TOKEN>"
</script>

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

The following fields are required to initialize the SDK:

client-id
data-sdk-client-token from setting up your server.

Initialize Fastlane component

// instantiates the Fastlane module
const fastlane = await window.paypal.Fastlane({
  FastlanePaymentComponent, // used for quick start integration
  FastlaneCardComponent, // used for flexible integration
  FastlaneWatermarkComponent
// For more details about available options parameters, see the Reference section.
});

// Convenience parameters for calling later on
const { identity, profile } = fastlane;

Specify locale

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

fastlane.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

2. Capture user email address

PayPal is a data controller and business under the California Consumer Privacy Act. You'll be sharing consumer's email addresses with PayPal. We recommend you make PayPal known to your consumers by leveraging our SDK to render the "Powered by Fastlane" logo and information tooltip. If you have any questions about this feature or your compliance with data protection laws, consult your legal advisors.

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.

const {
  customerContextId
} = await identity.lookupCustomerByEmail( /* email address */ );

Authenticate profile with one-time password

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:

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

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

//this variable  will turn to True if user authenticates successfully with OTP
//will remain False by default

 let renderFastlaneMemberExperience = false;

if (customerContextId) {
  // Email is associated with a Fastlane member or a PayPal member,
  // send customerContextId to trigger the authentication flow.
  const {
    authenticationState,
    profileData
  } = await identity.triggerAuthenticationFlow(customerContextId);

  if (authenticationState === "succeeded") {
    // Fastlane member successfully authenticated themselves
    // profileData contains their profile details

    renderFastlaneMemberExperience = true;

    const name = profileData.name;
    const shippingAddress = profileData.shippingAddress;
    const card = profileData.card;
} else {
  // Member failed or canceled authentication. Treat them as a guest payer
  renderFastlaneMemberExperience = false;
  }
} else {
  // No profile found with this email address. This is a guest payer
  renderFastlaneMemberExperience = false;
}

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.

3. Render shipping address

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.

Note: Shipping is available to merchants in the US only. However, PayPal doesn't have restrictions on shipping addresses, so the merchant can decide who they want to ship to. This can be done using the allowedShippingLocations parameter in the SDK. The merchant can disallow either countries or regions, states, or provinces and PayPal will honor that in our shipping address component and forms.

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:

// Code to execute when a user clicks on changeAddressButton
if (renderFastlaneMemberExperience) {
  if (profileData.shippingAddress) {
    // Render shipping address from the profile
    const {
      selectedAddress,
      selectionChanged
    } = await profile.showShippingAddressSelector();
    if (selectionChanged) {
      // selectedAddress contains the new address
    } else {
      // Selection modal was dismissed without selection
    }
  } else {
    // Render your shipping address form
  }
} else {
  // Render your shipping address form
}

4. Accept payments

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

Quick start

The quick start payment integration loads a pre-built template form to collect payments, requiring less integration effort. It is also PCI DSS compliant, ensuring that customer payment information is handled securely.

The pre-built payment UI component automatically renders the following:

Selected card for the Fastlane member.
"Change card" link which allows payers to change the selection or add a new card.
Card fields for guest users or for Fastlane members who don't have a card in their profile.
Billing address fields.

Add the Fastlane button

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

Collect shipping address and prefill phone field

const shippingAddress = {
  firstName: "Jen",
  lastName: "Smith",
  company: "Braintree",
  streetAddress: "1 E 1st St",
  extendedAddress: "5th Floor",
  locality: "Bartlett",
  region: "IL", // must be sent in 2-letter format
  postalCode: "60103",
  countryCodeAlpha2: "US",
  phoneNumber: "14155551212"
}

const options = {
  fields: {
    phoneNumber: {
      // Example of how to prefill the phone number field in the FastlanePaymentComponent
      prefill: "4026607986"
    }
  },
  styles: {
    root: {   //specify styles here
      backgroundColorPrimary: "#ffffff"
    }
  }
};

const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
    options,
    shippingAddress
  });
  await fastlanePaymentComponent.render("#payment-container");

// event listener when the user clicks to place the order
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", async ()=> {
  const { id } = await fastlanePaymentComponent.getPaymentToken();

  // Send the paymentToken and previously captured device data to server
  // to complete checkout
});

After you receive the paymentTokenId from the paymentToken object, send the paymentTokenId to your server to create a transaction with it.

For more information on the options you can pass to the functions in the previous code sample, see Customize your integration.

Render watermark

When displaying the card from the payer's Fastlane profile, you must inform them by displaying the Fastlane watermark below the card.

For a better payer experience of Fastlane, preload the watermark asset by adding the following code to the <head> section of the page:

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

Flexible

The flexible payment integration enables you to customize and style the payment page to the look and feel of your website. You can customize how you render:

The shipping address and payment method fields for guest users.
The shipping address and payment method fields for Fastlane members.

Integration requirements

You'll need to vary your integration for each use case.

For Fastlane members with a stored card, you'll need to render:

The selected card from the profile object
The Fastlane watermark
The change card button that invokes showCardSelector()

For Fastlane members with no card, an unsupported card, and guest payers, you'll need to render:

The FastlaneCardComponent to accept new card information.
A form to capture the payer's billing address.

Pass the billing address and cardholder name in the getPaymentToken() method. When calling the getPaymentToken() method, include the billing address in the request.

If the cardholderName field is disabled in your checkout process, it must still be sent in the getPaymentToken() request.

const name = profileData.name;
const shippingAddress = profileData.shippingAddress;
const card = profileData.card;

var selectedCardForCheckout = card;

if (memberAuthenticatedSuccessfully && card) {
    // render the card here
    // render Fastlane watermark
    // render a change button and call `profile.showCardSelector()` when it is clicked
} else {
  // User is a guest, failed to authenticate or does not have a card in the profile.
  // render the card fields

    const fastlaneCardComponentOptions = {
    fields: {
      phoneNumber: {
        // Example of how to prefill the phone number field in the FastlaneCardComponent
        prefill: "4026607986"
      },
      cardholderName: {
        //Example of enabling and prefilling the cardholder name field
        prefill: "John Doe",
        enabled: true
      }
    },
    styles: {
      root: {   //specify styles here
        backgroundColorPrimary: "#ffffff"
      }
    }
  };
  const fastlaneCardComponent = await fastlane.FastlaneCardComponent(
    fastlaneCardComponentOptions
  );
  fastlaneCardComponent.render("#card-container");
}

// Handle changes to the card selection
const changeCardButton = document.getElementById("change-card-button");
changeCardButton.addEventListener("click", async ()=> {
  const { selectionChanged, selectedCard } = await profile.showCardSelector();
  if (selectionChanged) {
    // selectedCard contains the new card
    // selectedCard.id contains the paymentToken
    // selectedCard.paymentSource.card contains more details such as last 4 card dits

    selectedCardForCheckout = selectedCard

    // re-render the selected card UI if required
  } else {
    // selection modal was dismissed without selection
  }
});

// Handle form submission
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", async ()=> {
  var paymentToken = null;
  // if the card component is rendered, pass the billing address and get the payment token
  if (selectedCardForCheckout) {
    paymentToken = selectedCardForCheckout.id;
  } else {
    paymentToken = await fastlaneCardComponent.getPaymentToken({
      billingAddress: {
        addressLine1: "2211 North 1st St",
        adminArea1: "CA",
        adminArea2: "San Jose",
        postalCode: "95131",
        countryCode: "US"
      }
    });
  }

  // Send the paymentToken ID and previously captured device data to server
  // to complete checkout
});

Render watermark

When displaying the card from the payer's Fastlane profile, you must inform them by displaying the Fastlane watermark below the card.

For a better payer experience of Fastlane, preload the watermark asset by adding the following code to the <head> section of the page:

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

Display watermark with info icon

The image tag in the watermark container div allows the watermark to render instantly.

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

Display watermark without info icon

The image tag in the watermark container div allows the watermark to render instantly.

The mouse-over tooltip functionality is added to the image when the Watermark component completes loading. After it loads, the information is displayed when the user hovers over the i icon.

Load card assets for the selected card so that the payer can see their card brand.

<!-- add a div where the watermark will render -->
<div id="watermark-container">
  <img src="https://www.paypalobjects.com/fastlane-v1/assets/fastlane_en_sm_light.0296.svg" />
</div>

2. Integrate back end

1. Create order

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.

Direct capture Orders API checkout with shipping

curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
 -H 'PayPal-Request-Id: UNIQUE_ID' \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-TOKEN' \
 -H 'Authorization: Bearer PAYPAL_ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -H 'PayPal-Client-Metadata-Id: <CM_ID>' \
 -d '{
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "single_use_token": "1h371660pr490622k" //paymentToken from the client
    }
  },
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "50.00",
        "breakdown": {
          "item_total": {
            "currency_code": "USD",
            "value": "40.00"
          },
          "shipping": {
            "currency_code": "USD",
            "value": "10.00"
          }
        }
      },
      "items": [
        {
          "name": "Coffee",
          "description": "1 lb Kona Island Beans",
          "sku": "sku03",
          "unit_amount": {
            "currency_code": "USD",
            "value": "40.00"
          },
          "quantity": "1",
          "category": "PHYSICAL_GOODS",
          "image_url": "https://example.com/static/images/items/1/kona_coffee_beans.jpg",
          "url": "https://example.com/items/1/kona_coffee_beans",
          "upc": {
            "type": "UPC-A",
            "code": "987654321015"
          }
        }
      ],
      "shipping": {
        "type": "SHIPPING",
        "name": {
          "full_name": "Lawrence David"
        },
        "address": {
          "address_line_1": "585 Moreno Ave",
          "admin_area_2": "Los Angeles",
          "admin_area_1": "CA", //must be sent in 2-letter format
          "postal_code": "90049",
          "country_code": "US"
        },
        "phone_number": {
          "country_code": "1",
          "national_number": "5555555555"
        }
      }
    }
  ]
}'

Special use cases

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: You can save a payment method with or without a transaction.

Vault with transaction: 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 payment token, which can be vaulted before or after a transaction and used for future transactions. See the Orders v2 documentation for more details.
Vault without transaction: If you want to save the paymentToken returned by the Fastlane SDK without completing the transaction, then the payment token is generated but the Fastlane profile is not created for the customer. The Fastlane profile is created only for vaulting customers if they also complete a transaction during checkout.

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.

Quick start

Guest payers

Guest payers enter an email not associated with a PayPal account or Fastlane profile. Make sure you have the following before you start testing the guest payer flow:

New email address: Provide a new email address not associated with a sandbox Fastlane account.
Ensure opt-in toggle is ON: Go through the checkout process using one of the test card numbers. Be sure that the opt-in toggle is on.
Phone number for sandbox: Enter any valid phone number. Make sure to pass a valid area code and prefix. A Fastlane profile is not created if you pass an invalid number such as 111-111-1111. No SMS is sent in sandbox mode.

When you complete the transaction with the consent toggle on, a Fastlane profile is created. Use that profile to test transactions as a Fastlane member.

Guest opts out of Fastlane

User flow, Result
User flow	Result
The `FastlanePaymentComponent` renders card fields and the consent toggle. The buyer turns the consent toggle off and completes the order.	The payment is completed successfully and no Fastlane profile is created.

Guest opts in to Fastlane

User flow, Result
User flow	Result
The `FastlanePaymentComponent` renders card fields and the consent toggle. The buyer completes the order with the consent toggle on.	The payment is completed successfully and a Fastlane profile is created for the email the guest entered.

Member testing

A Fastlane member enters a recognized email at checkout.

A Fastlane member profile: Go through the previous step 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.
OTP for testing: When the authentication modal appears and you are prompted for a one-time password (OTP) use 111111 to trigger a successful authentication and any other 6-digit number to simulate a failed authentication.

Note: Make sure to test the payer's ability to update the addresses and cards associated with their profile.

Scenario, User flow, Result
Scenario	User flow	Result
Happy path	The one-time password (OTP) flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry.	The buyer completes the order.
OTP failed or cancelled	The OTP flow is triggered to authenticate the buyer. Cancel the OTP by exiting or entering an incorrect code.	The `FastlanePaymentComponent` renders the card fields with no consent toggle. The buyer completes the order.
New address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI. Select Add new address and enter a new address in the address selector UI.	The buyer completes the order. A new address is added to the buyer's Fastlane profile.
New card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI. Select Add new card and enter a new card in the card selector UI.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
Change address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI via `showAddressSelector()`. Select another address from the list.	The buyer completes the order with changed address.
Change card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI via `showCardSelector()`. Select another card from the list.	The buyer completes the order with selected card.
No card or unsupported card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. The payment component renders card fields to capture a new card.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
No address or address in unsupported region	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. The payment component renders card fields to capture a new card.	The buyer completes the order. A new shipping address is added to the buyer's Fastlane profile.

PayPal member testing

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.

Card numbers for testing

Use the following test card numbers for sandbox transactions:

Brand, Card number
Brand	Card number
Visa	4005 5192 0000 0004
Visa	4012 0000 3333 0026
Visa	4012 0000 7777 7777
Mastercard	5555 5555 5555 4444
American Express	3782 822463 10005

Flexible

Guest payers

Guest payers enter an email not associated with a PayPal account or Fastlane profile. Make sure you have the following before you start testing the guest payer flow:

New email address: Provide a new email address not associated with a sandbox Fastlane account.
Ensure opt-in toggle is ON: Go through the checkout process using one of the test card numbers. Be sure that the opt-in toggle is on.
Phone number for sandbox: Enter any valid phone number. No SMS is sent in sandbox mode.

When you complete the transaction with the consent toggle on, a Fastlane profile is created. Use that profile to test transactions as a Fastlane member.

Guest opts out of Fastlane

User flow, Result
User flow	Result
Shipping address fields are rendered. The `FastlaneCardComponent` renders card fields and the consent toggle. The buyer turns the consent toggle off and completes the order.	The payment is completed successfully and no Fastlane profile is created.

Guest opts in to Fastlane

User flow, Result
User flow	Result
Shipping address fields are rendered. The `FastlaneCardComponent` renders card fields and the consent toggle. The buyer turns the consent toggle on and completes the order.	The payment is completed successfully and a Fastlane profile is created for the email the guest entered.

Member testing

A Fastlane member enters a recognized email at checkout.

Scenario, User flow, Result
Scenario	User flow	Result
Happy path	The one-time password (OTP) flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry.	The buyer completes the order.
OTP failed or cancelled	The OTP flow is triggered to authenticate the buyer. Cancel the OTP by exiting or entering an incorrect code.	The `FastlaneCardComponent` renders the card fields with no consent toggle. The buyer completes the order.
New address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI. Select Add new address and enter a new address in the address selector UI.	The buyer completes the order. A new address is added to the buyer's Fastlane profile.
New card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI. Select Add new card and enter a new card in the card selector UI.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
Change address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI via `showAddressSelector()`. Select another address from the list.	The buyer completes the order with changed address.
Change card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI via `showCardSelector()`. Select another card from the list.	The buyer completes the order with selected card.
No card or unsupported card	The OTP flow is triggered to authenticate the buyer. After OTP entry, no card information is present on the returned profile object. Shipping address information is rendered based on the returned profile object. `FastlaneCardComponent` is rendered to collect new card information. No consent toggle is shown.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
No address or address in unsupported region	The OTP flow is triggered to authenticate the buyer. After OTP entry, no shipping address information is present on the returned profile object. Card information should be rendered based on the returned profile object. Address collection form should be rendered. Enter a new address.	The buyer completes the order. A new shipping address is added to the buyer's Fastlane profile.

PayPal member testing

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:

Brand, Card number
Brand	Card number
Visa	4005 5192 0000 0004
Visa	4012 0000 3333 0026
Visa	4012 0000 7777 7777
Mastercard	5555 5555 5555 4444
American Express	3782 822463 10005

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.

Select Advanced Credit and Debit Card Payments on your REST app. The merchant will be signed up for advanced credit and debit after onboarding through the Partner Referral API.

Next step

Optionally customize your Fastlane integration.

Fastlane reference

Troubleshooting, FAQs, and how to customize your integration.

Availability

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.

1. Integrate front-end

Set up your client side to integrate Fastlane.

1. Initialize SDK and Fastlane

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

<script>
  src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>>&components=buttons,fastlane"
  data-sdk-client-token="<SDK_CLIENT_TOKEN>"
</script>

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

The following fields are required to initialize the SDK:

client-id
data-sdk-client-token from setting up your server.

Initialize Fastlane component

// instantiates the Fastlane module
const fastlane = await window.paypal.Fastlane({
  FastlanePaymentComponent, // used for quick start integration
  FastlaneCardComponent, // used for flexible integration
  FastlaneWatermarkComponent
// For more details about available options parameters, see the Reference section.
});

// Convenience parameters for calling later on
const { identity, profile } = fastlane;

Specify locale

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

fastlane.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

2. Capture user email address

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.

const {
  customerContextId
} = await identity.lookupCustomerByEmail( /* email address */ );

Authenticate profile with one-time password

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

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

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

//this variable  will turn to True if user authenticates successfully with OTP
//will remain False by default

 let renderFastlaneMemberExperience = false;

if (customerContextId) {
  // Email is associated with a Fastlane member or a PayPal member,
  // send customerContextId to trigger the authentication flow.
  const {
    authenticationState,
    profileData
  } = await identity.triggerAuthenticationFlow(customerContextId);

  if (authenticationState === "succeeded") {
    // Fastlane member successfully authenticated themselves
    // profileData contains their profile details

    renderFastlaneMemberExperience = true;

    const name = profileData.name;
    const shippingAddress = profileData.shippingAddress;
    const card = profileData.card;
} else {
  // Member failed or canceled authentication. Treat them as a guest payer
  renderFastlaneMemberExperience = false;
  }
} else {
  // No profile found with this email address. This is a guest payer
  renderFastlaneMemberExperience = false;
}

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.

3. Render shipping address

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:

// Code to execute when a user clicks on changeAddressButton
if (renderFastlaneMemberExperience) {
  if (profileData.shippingAddress) {
    // Render shipping address from the profile
    const {
      selectedAddress,
      selectionChanged
    } = await profile.showShippingAddressSelector();
    if (selectionChanged) {
      // selectedAddress contains the new address
    } else {
      // Selection modal was dismissed without selection
    }
  } else {
    // Render your shipping address form
  }
} else {
  // Render your shipping address form
}

4. Accept payments

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

Quick start

The pre-built payment UI component automatically renders the following:

Selected card for the Fastlane member.
"Change card" link which allows payers to change the selection or add a new card.
Card fields for guest users or for Fastlane members who don't have a card in their profile.
Billing address fields.

Add the Fastlane button

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

Collect shipping address and prefill phone field

const shippingAddress = {
  firstName: "Jen",
  lastName: "Smith",
  company: "Braintree",
  streetAddress: "1 E 1st St",
  extendedAddress: "5th Floor",
  locality: "Bartlett",
  region: "IL", // must be sent in 2-letter format
  postalCode: "60103",
  countryCodeAlpha2: "US",
  phoneNumber: "14155551212"
}

const options = {
  fields: {
    phoneNumber: {
      // Example of how to prefill the phone number field in the FastlanePaymentComponent
      prefill: "4026607986"
    }
  },
  styles: {
    root: {   //specify styles here
      backgroundColorPrimary: "#ffffff"
    }
  }
};

const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
    options,
    shippingAddress
  });
  await fastlanePaymentComponent.render("#payment-container");

// event listener when the user clicks to place the order
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", async ()=> {
  const { id } = await fastlanePaymentComponent.getPaymentToken();

  // Send the paymentToken and previously captured device data to server
  // to complete checkout
});

After you receive the paymentTokenId from the paymentToken object, send the paymentTokenId to your server to create a transaction with it.

For more information on the options you can pass to the functions in the previous code sample, see Customize your integration.

Render watermark

When displaying the card from the payer's Fastlane profile, you must inform them by displaying the Fastlane watermark below the card.

For a better payer experience of Fastlane, preload the watermark asset by adding the following code to the <head> section of the page:

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

Flexible

The flexible payment integration enables you to customize and style the payment page to the look and feel of your website. You can customize how you render:

The shipping address and payment method fields for guest users.
The shipping address and payment method fields for Fastlane members.

Integration requirements

You'll need to vary your integration for each use case.

For Fastlane members with a stored card, you'll need to render:

The selected card from the profile object
The Fastlane watermark
The change card button that invokes showCardSelector()

For Fastlane members with no card, an unsupported card, and guest payers, you'll need to render:

The FastlaneCardComponent to accept new card information.
A form to capture the payer's billing address.

Pass the billing address and cardholder name in the getPaymentToken() method. When calling the getPaymentToken() method, include the billing address in the request.

If the cardholderName field is disabled in your checkout process, it must still be sent in the getPaymentToken() request.

const name = profileData.name;
const shippingAddress = profileData.shippingAddress;
const card = profileData.card;

var selectedCardForCheckout = card;

if (memberAuthenticatedSuccessfully && card) {
    // render the card here
    // render Fastlane watermark
    // render a change button and call `profile.showCardSelector()` when it is clicked
} else {
  // User is a guest, failed to authenticate or does not have a card in the profile.
  // render the card fields

    const fastlaneCardComponentOptions = {
    fields: {
      phoneNumber: {
        // Example of how to prefill the phone number field in the FastlaneCardComponent
        prefill: "4026607986"
      },
      cardholderName: {
        //Example of enabling and prefilling the cardholder name field
        prefill: "John Doe",
        enabled: true
      }
    },
    styles: {
      root: {   //specify styles here
        backgroundColorPrimary: "#ffffff"
      }
    }
  };
  const fastlaneCardComponent = await fastlane.FastlaneCardComponent(
    fastlaneCardComponentOptions
  );
  fastlaneCardComponent.render("#card-container");
}

// Handle changes to the card selection
const changeCardButton = document.getElementById("change-card-button");
changeCardButton.addEventListener("click", async ()=> {
  const { selectionChanged, selectedCard } = await profile.showCardSelector();
  if (selectionChanged) {
    // selectedCard contains the new card
    // selectedCard.id contains the paymentToken
    // selectedCard.paymentSource.card contains more details such as last 4 card dits

    selectedCardForCheckout = selectedCard

    // re-render the selected card UI if required
  } else {
    // selection modal was dismissed without selection
  }
});

// Handle form submission
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", async ()=> {
  var paymentToken = null;
  // if the card component is rendered, pass the billing address and get the payment token
  if (selectedCardForCheckout) {
    paymentToken = selectedCardForCheckout.id;
  } else {
    paymentToken = await fastlaneCardComponent.getPaymentToken({
      billingAddress: {
        addressLine1: "2211 North 1st St",
        adminArea1: "CA",
        adminArea2: "San Jose",
        postalCode: "95131",
        countryCode: "US"
      }
    });
  }

  // Send the paymentToken ID and previously captured device data to server
  // to complete checkout
});

Render watermark

When displaying the card from the payer's Fastlane profile, you must inform them by displaying the Fastlane watermark below the card.

For a better payer experience of Fastlane, preload the watermark asset by adding the following code to the <head> section of the page:

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

Display watermark with info icon

The image tag in the watermark container div allows the watermark to render instantly.

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

Display watermark without info icon

The image tag in the watermark container div allows the watermark to render instantly.

The mouse-over tooltip functionality is added to the image when the Watermark component completes loading. After it loads, the information is displayed when the user hovers over the i icon.

Load card assets for the selected card so that the payer can see their card brand.

<!-- add a div where the watermark will render -->
<div id="watermark-container">
  <img src="https://www.paypalobjects.com/fastlane-v1/assets/fastlane_en_sm_light.0296.svg" />
</div>

2. Integrate back end

1. Create order

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.

Direct capture Orders API checkout with shipping

curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
 -H 'PayPal-Request-Id: UNIQUE_ID' \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-TOKEN' \
 -H 'Authorization: Bearer PAYPAL_ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -H 'PayPal-Client-Metadata-Id: <CM_ID>' \
 -d '{
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "single_use_token": "1h371660pr490622k" //paymentToken from the client
    }
  },
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "50.00",
        "breakdown": {
          "item_total": {
            "currency_code": "USD",
            "value": "40.00"
          },
          "shipping": {
            "currency_code": "USD",
            "value": "10.00"
          }
        }
      },
      "items": [
        {
          "name": "Coffee",
          "description": "1 lb Kona Island Beans",
          "sku": "sku03",
          "unit_amount": {
            "currency_code": "USD",
            "value": "40.00"
          },
          "quantity": "1",
          "category": "PHYSICAL_GOODS",
          "image_url": "https://example.com/static/images/items/1/kona_coffee_beans.jpg",
          "url": "https://example.com/items/1/kona_coffee_beans",
          "upc": {
            "type": "UPC-A",
            "code": "987654321015"
          }
        }
      ],
      "shipping": {
        "type": "SHIPPING",
        "name": {
          "full_name": "Lawrence David"
        },
        "address": {
          "address_line_1": "585 Moreno Ave",
          "admin_area_2": "Los Angeles",
          "admin_area_1": "CA", //must be sent in 2-letter format
          "postal_code": "90049",
          "country_code": "US"
        },
        "phone_number": {
          "country_code": "1",
          "national_number": "5555555555"
        }
      }
    }
  ]
}'

Special use cases

Vaulting: You can save a payment method with or without a transaction.

Vault with transaction: 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 payment token, which can be vaulted before or after a transaction and used for future transactions. See the Orders v2 documentation for more details.
Vault without transaction: If you want to save the paymentToken returned by the Fastlane SDK without completing the transaction, then the payment token is generated but the Fastlane profile is not created for the customer. The Fastlane profile is created only for vaulting customers if they also complete a transaction during checkout.

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.

Quick start

Guest payers

Guest payers enter an email not associated with a PayPal account or Fastlane profile. Make sure you have the following before you start testing the guest payer flow:

New email address: Provide a new email address not associated with a sandbox Fastlane account.
Ensure opt-in toggle is ON: Go through the checkout process using one of the test card numbers. Be sure that the opt-in toggle is on.
Phone number for sandbox: Enter any valid phone number. Make sure to pass a valid area code and prefix. A Fastlane profile is not created if you pass an invalid number such as 111-111-1111. No SMS is sent in sandbox mode.

When you complete the transaction with the consent toggle on, a Fastlane profile is created. Use that profile to test transactions as a Fastlane member.

Guest opts out of Fastlane

User flow, Result
User flow	Result
The `FastlanePaymentComponent` renders card fields and the consent toggle. The buyer turns the consent toggle off and completes the order.	The payment is completed successfully and no Fastlane profile is created.

Guest opts in to Fastlane

User flow, Result
User flow	Result
The `FastlanePaymentComponent` renders card fields and the consent toggle. The buyer completes the order with the consent toggle on.	The payment is completed successfully and a Fastlane profile is created for the email the guest entered.

Member testing

A Fastlane member enters a recognized email at checkout.

A Fastlane member profile: Go through the previous step 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.
OTP for testing: When the authentication modal appears and you are prompted for a one-time password (OTP) use 111111 to trigger a successful authentication and any other 6-digit number to simulate a failed authentication.

Note: Make sure to test the payer's ability to update the addresses and cards associated with their profile.

Scenario, User flow, Result
Scenario	User flow	Result
Happy path	The one-time password (OTP) flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry.	The buyer completes the order.
OTP failed or cancelled	The OTP flow is triggered to authenticate the buyer. Cancel the OTP by exiting or entering an incorrect code.	The `FastlanePaymentComponent` renders the card fields with no consent toggle. The buyer completes the order.
New address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI. Select Add new address and enter a new address in the address selector UI.	The buyer completes the order. A new address is added to the buyer's Fastlane profile.
New card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI. Select Add new card and enter a new card in the card selector UI.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
Change address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI via `showAddressSelector()`. Select another address from the list.	The buyer completes the order with changed address.
Change card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI via `showCardSelector()`. Select another card from the list.	The buyer completes the order with selected card.
No card or unsupported card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. The payment component renders card fields to capture a new card.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
No address or address in unsupported region	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. The payment component renders card fields to capture a new card.	The buyer completes the order. A new shipping address is added to the buyer's Fastlane profile.

PayPal member testing

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.

Card numbers for testing

Use the following test card numbers for sandbox transactions:

Brand, Card number
Brand	Card number
Visa	4005 5192 0000 0004
Visa	4012 0000 3333 0026
Visa	4012 0000 7777 7777
Mastercard	5555 5555 5555 4444
American Express	3782 822463 10005

Flexible

Guest payers

Guest payers enter an email not associated with a PayPal account or Fastlane profile. Make sure you have the following before you start testing the guest payer flow:

New email address: Provide a new email address not associated with a sandbox Fastlane account.
Ensure opt-in toggle is ON: Go through the checkout process using one of the test card numbers. Be sure that the opt-in toggle is on.
Phone number for sandbox: Enter any valid phone number. No SMS is sent in sandbox mode.

When you complete the transaction with the consent toggle on, a Fastlane profile is created. Use that profile to test transactions as a Fastlane member.

Guest opts out of Fastlane

User flow, Result
User flow	Result
Shipping address fields are rendered. The `FastlaneCardComponent` renders card fields and the consent toggle. The buyer turns the consent toggle off and completes the order.	The payment is completed successfully and no Fastlane profile is created.

Guest opts in to Fastlane

User flow, Result
User flow	Result
Shipping address fields are rendered. The `FastlaneCardComponent` renders card fields and the consent toggle. The buyer turns the consent toggle on and completes the order.	The payment is completed successfully and a Fastlane profile is created for the email the guest entered.

Member testing

A Fastlane member enters a recognized email at checkout.

Scenario, User flow, Result
Scenario	User flow	Result
Happy path	The one-time password (OTP) flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry.	The buyer completes the order.
OTP failed or cancelled	The OTP flow is triggered to authenticate the buyer. Cancel the OTP by exiting or entering an incorrect code.	The `FastlaneCardComponent` renders the card fields with no consent toggle. The buyer completes the order.
New address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI. Select Add new address and enter a new address in the address selector UI.	The buyer completes the order. A new address is added to the buyer's Fastlane profile.
New card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI. Select Add new card and enter a new card in the card selector UI.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
Change address	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change address link to invoke the address selector UI via `showAddressSelector()`. Select another address from the list.	The buyer completes the order with changed address.
Change card	The OTP flow is triggered to authenticate the buyer. The buyer's shipping address and card information are populated after OTP entry. Select the change card link to invoke the card selector UI via `showCardSelector()`. Select another card from the list.	The buyer completes the order with selected card.
No card or unsupported card	The OTP flow is triggered to authenticate the buyer. After OTP entry, no card information is present on the returned profile object. Shipping address information is rendered based on the returned profile object. `FastlaneCardComponent` is rendered to collect new card information. No consent toggle is shown.	The buyer completes the order. A new card is added to the buyer's Fastlane profile.
No address or address in unsupported region	The OTP flow is triggered to authenticate the buyer. After OTP entry, no shipping address information is present on the returned profile object. Card information should be rendered based on the returned profile object. Address collection form should be rendered. Enter a new address.	The buyer completes the order. A new shipping address is added to the buyer's Fastlane profile.

PayPal member testing

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:

Brand, Card number
Brand	Card number
Visa	4005 5192 0000 0004
Visa	4012 0000 3333 0026
Visa	4012 0000 7777 7777
Mastercard	5555 5555 5555 4444
American Express	3782 822463 10005

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.

Select Advanced Credit and Debit Card Payments on your REST app. The merchant will be signed up for advanced credit and debit after onboarding through the Partner Referral API.

Next step

Optionally customize your Fastlane integration.

Fastlane reference

Troubleshooting, FAQs, and how to customize your integration.

Integrate Fastlane

On this page

On this page

On this page

If you accept cookies, we'll use them to improve and customise your experience and enable our partners to show you personalised PayPal ads when you visit other sites. Manage cookies and learn more

Integrate Fastlane

On this page

On this page