Upgrade to Fastlane

BetaDocs

Last updated: Feb 27th, 8:46am

Know before you code

Required
Get sandbox account information

Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

Your client ID. Use your client ID when adding payment options to your website.

Your personal and business sandbox accounts. Use sandbox accounts to test checkout options.

Optional
Verify sandbox account setup

This integration requires a sandbox business account. The sandbox account should automatically be set up for Fastlane, but to confirm:

Log into the PayPal Developer Dashboard, toggle Sandbox, and go to Apps & Credentials.

In REST API apps, select or create an app.

Go to Features > Accept payments.

Check if Fastlane and Vault are enabled. If not, select the Fastlane and Vault checkboxes and select Save Changes.

If you have a PayPal or cards integration with the Orders v2 API, you can upgrade to Fastlane.

Upgrade PayPal

Update existing script

The following is the script for the PayPal button:

1<script src="https://www.paypal.com/sdk/js?components=buttons&client-id=<%= clientId %>"></script>

Add the Fastlane option and pass the data-sdk-client-token and data-client-metadata-id to the components section of your script:

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>

Capture email address

In addition to displaying PayPal as an upstream presentment option, be sure to display a field to collect the payer's email address. After collecting the email address, use the following code to determine whether the email is associated with a Fastlane profile or belongs to a PayPal member.

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

Determine if Fastlane profile is associated with email

If the user is determined to have a Fastlane profile, they must authenticate before Fastlane retrieves their saved payment information and address. They are presented with a screen to authenticate themselves by entering an OTP sent to their registered mobile number.

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

If you want to render a shipping address:

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

Populate info for Fastlane members

If the user is identified as a Fastlane user, use the following code to prefill the card and shipping address:

1const shippingAddress = {
2  name: {
3    firstName: "Jen",
4    lastName: "Smith"
5  },
6  address: {
7    addressLine1: "1 E 1st St",
8    addressLine2: "5th Floor",
9    adminArea1: "Bartlett",
10    adminarea2: "IL",
11    postalCode: "60103",
12    countryCode: "US",
13    phone: "16503551233"
14  }
15};
16const options = {
17  fields: {
18    phoneNumber: {
19      // Example of how to prefill the phone number field in the FastlanePaymentComponent
20      prefill: "4026607986"
21    }
22  },
23  styles: {
24    root: {   //specify styles here
25      backgroundColorPrimary: "#ffffff"
26    }
27  }
28};
29const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
30    options,
31    shippingAddress
32  });
33fastlanePaymentComponent.render("#payment-container");
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  // Send the paymentToken and previously captured device data to server
39  // to complete checkout
40});

Collect info from guest user

You can use the quick start integration to collect payment and billing information.

Add the FastlanePaymentComponent to the div container and create a button to submit the information gathered from FastlanePaymentComponent .

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

Collect the shipping address and prefill the phone number field:

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

Integrate server side

You can use the orders API request that you have built on the server side to pass the payment, billing, and shipping address information to capture the transaction:

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

Test your integration

After upgrading to Fastlane, test your integration in the sandbox environment. For information on simulating successful payments and generating card errors, refer to Card testing.

To test your Fastlane integration, refer to the Fastlane integration testing guide.

Go live

If you have fulfilled the requirements for accepting payments via Fastlane for your business account, you can Move your app to production.

Upgrade Card

1. Update existing script

The existing script for card fields for your integration may be similar to the following:

1<script src="https://www.paypal.com/sdk/js?components=buttons,card-fields&client-id=<%= clientId %>"></script>

Add the Fastlane option and pass the data-sdk-client-token and data-client-metadata-id to the components section of your script:

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>

2. Capture email address

Display a field to collect an email address. After collecting the email address, use the following code to determine whether the email is associated with a Fastlane profile or belongs to a PayPal member.

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

3. Determine if Fastlane profile is associated with email

If the user is determined to have a Fastlane profile, they must authenticate before Fastlane retrieves their saved payment information and address associated with their profile. They are presented with a screen to authenticate themselves by entering an OTP sent to their registered mobile number.

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}

If you want to render a shipping address:

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}

4. Populate info for Fastlane members

If the user is identified as a Fastlane user, use the following code to prefill the card and shipping address:

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

5. Collect info from guest user

Retrieve the existing card integration that you use to collect payment and billing information.

6. Integrate server side

You can use the orders API request that you have built on the server side to pass the payment, billing, and shipping address information to capture the transaction:

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

7. Test your integration

After upgrading to Fastlane, test your integration in the sandbox environment. For information on simulating successful payments and generating card errors, refer to Card testing.

To test your Fastlane integration, refer to the Fastlane integration testing guide.

8. Go live

If you have fulfilled the requirements for accepting payments via Fastlane for your business account, you can Move your app to production.

Next steps

Set up your development environment and integrate Fastlane.

Required
Set up your development environment

Configure your REST account and initialize the SDK.

Required
Integrate Fastlane

Use our ready-made quickstart integration or customize form fields with our flexible integration.