Upgrade to Fastlane

DocsBetaLast updated: August 1st 2024, @ 11:23:55 am

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.

Dashboard

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.

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

2. Capture email address

Along with displaying PayPal as an upstream presentment option, also 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. 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}

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};
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});

5. 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    });

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.