Flexible Integration

The Flexible Integration allows developers to customize the payment experience for their users. This approach offers more control and flexibility compared to the Quick Start Integration, enabling you to tailor the payment flow to meet specific business requirements. This guide will walk you through the steps to implement Flexible Integration on the client side, highlighting areas where it differs from Quick Start Integration. For a faster, default setup, refer to the Quick Start Integration Guide.

Quick Start vs Flexible Integration

The table below outlines the key differences between Quick Start and Flexible Integration. Use this as a reference to determine which integration method is best suited for your project.

Client-side Integration

Step 1: Initialize the Braintree SDK

• Load the necessary Braintree SDK modules.
• Ensure all modules are the same version (3.120.0 or greater).

<script src="https://js.braintreegateway.com/web/3.116.0/js/client.min.js"></script>
  <script src="https://js.braintreegateway.com/web/3.116.0/js/fastlane.js"></script>
  <script src="https://js.braintreegateway.com/web/3.116.0/js/data-collector.min.js"></script>

Step 2: Initialize Fastlane Component

• Create a client instance.
• Create a data collector instance.
• Define custom styling for the Fastlane component (Optional).
• Initialize Fastlane component.
• Define the customer's locale (Optional).
• Define the merchant's accepted card brands (Optional).
• Extract identity, profile and events from the braintree.fastlane.create function response as local variables

const clientInstance = await braintree.client.create({
  authorization: "<YOUR CLIENT TOKEN>"
});

   const dataCollectorInstance = await braintree.dataCollector.create({
    client: clientInstance,
    riskCorrelationId: "<SESSION ID>"
});

   const styles = {
    //specify global styles here
    root: {
      backgroundColorPrimary: "#ffffff"
    }
 }

   const deviceData = dataCollectorInstance.deviceData;

   // For all configuration options for the fastlane construct 
   // please refer to the Reference types section
   const fastlane = await braintree.fastlane.create({
   authorization: "<YOUR CLIENT TOKEN>",
   client: clientInstance,
   deviceData: deviceData,
   styles: styles
 });

   const identity = fastlane.identity;
   const profile = fastlane.profile;

Step 3: Render Email Field Fastlane Watermark

• Add a div for the watermark.
• Display the Fastlane watermark with the email input field.

When sharing the email with Fastlane, certain countries and regulations require you to display the Fastlane watermark to inform consumers about the data sharing.

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

The image tag within the watermark container div ensures the watermark is rendered immediately.

const fastlaneWatermark = (await fastlane.FastlaneWatermarkComponent({
    includeAdditionalInfo: true
}));
await fastlaneWatermark.render("#watermark-container");

Step 4: Customer Lookup and Authentication

• Lookup the customer by email.
• Trigger authentication flow if the customer is a Fastlane member.
• Retrieve authentication state and profile data.

After collecting the email address, call identity.lookupCustomerByEmail(email) to check if the email is associated with a Fastlane or PayPal member.

Fastlane members must authenticate themselves before their profile information can be accessed. They will receive an OTP on their registered mobile number or alternate methods to complete the authentication.

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

   var 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 cancelled to authenticate. Treat them as a guest payer
    renderFastlaneMemberExperience = false;
    }
   } else {
   // No profile found with this email address. This is a guest payer
   renderFastlaneMemberExperience = false;
   }

• Succeeded Authentication: An authenticationState value of succeeded indicates a Fastlane member has authenticated and then you should set renderFastlaneMemberExperience to true.
• Guest User: Any other authenticationState value indicates a Fastlane guest user and you should render the guest experience specified in step 5.
• Profile Data: Fastlane members card details and shipping address are returned with the profileData object contents on successful authentication and the renderFastlaneMemberExperience is set to True.

Step 5: Fastlane Member Experience

• Render the customer's shipping address.
• Allow the customer to change their shipping address.
• Render the customer's card details.
  • Last 4 of card
  • Brand of card
  • Exp Date (Optional)
• Allow the customer to change their card.
• Render the Fastlane Watermark with the shipping and card details.

Render Shipping Address

Set change link

Code snippet NOT FOUND

Shipping Address Selector

if (renderFastlaneMemberExperience) {
    if (profileData.shippingAddress) {
    // render shipping address from the profile
  
    const changeAddressButton = document.getElementById("your-change-address-button");
    
    changeAddressButton.addEventListener("click", async () => {
      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
    }

Card details

Card Selector

Render the card details returned in the profileData object after successful authentication. Include a change link that will allow the customer to change to another card within their Fastlane profile.

Set Change Link

Code snippet NOT FOUND

Card Selector

Code snippet NOT FOUND

Step 6: Fastlane Guest Experience

• Have the customer enter their shipping address manually.
• Have the customer enter their billing address manually.
• Setup the Card Component.
• Define the event that triggers Fastlane to retrieve the payment token, typically on payment submission.
• Define the styling object to send as a parameter to the payment component (Optional)
• Define the fields object to prefill/disable available fields within the Card component (Optional)
• Render Card Component.
• When the event to trigger the Fastlane token occurs, call fastlaneCardComponent.getPaymentToken() to retrieve the payment token.

Only render the Card component if you have a Fastlane guest user or a Fastlane member who doesn't have a saved card.

Setup Card component and trigger for getPaymentToken:

Code snippet NOT FOUND

Render Card Component

Code snippet NOT FOUND

Generate Fastlane Payment Token

Code snippet NOT FOUND

• Use the Fastlane Payment token the same as a paymentMethodNonce to:
• Transact
• Vault