Upgrade to Fastlane

DocsBeta

Last updated: August 1st 2024, 11:53:55pm

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

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>

Upgrade Cards

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

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}

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

Collect info from guest user

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

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.

Know before you code

Get sandbox account information fastlane upgrade

Required
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

Verify sandbox account setup

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

Set up your development environment and integrate Fastlane.