Fastlane reference

Troubleshoot, read our FAQs, follow best practices, and customize your integration.

Troubleshooting

The following are common issues and steps to take to resolve them.

Authorization error while initializing Fastlane

This error indicates that your merchant account and your client credentials may not be fully provisioned for Fastlane. Talk to your account team for assistance.

Fastlane member doesn't have cards or addresses

Add a new card or address to the member's Fastlane profile. Complete the order. The payment should be completed successfully with the new card.

No payment token returned

If FastlaneCardComponent.getPaymentToken() doesn't return a token, ensure that you're passing all required parameters in the correct format.

Undefined methods returned

Fastlane has been disabled from within the PayPal dashboard if the identity.triggerAuthenticationFlow(), profile.showShippingAddressSelector(), or profile.showCardSelector() methods return undefined.

If the merchant has disabled Fastlane, the Fastlane client SDK reverts to the guest experience without the ability to opt-in to creating a Fastlane profile. This ensures there is no interruption to your buyers.

FAQs

Will Fastlane work if I save a payer's payment methods to the PayPal vault?

Yes, the paymentToken returned on the client can be saved to the vault. You can vault the paymentToken before transacting or transact before vaulting. PayPal only supports vaulting when using the store_in_vault attribute of the create order request.

Fastlane does not support a flow where a customer or payment_method is created prior to a transaction.

How long is a payment token valid?

A paymentToken is valid for 3 hours from the time of issuance.

What if the payer's shipping address is in a location that my site does not ship to?

When you initially call window.paypal.fastlane.create(), you have the option of passing in a list of allowed locations using the addressOptions object.

How should I handle when a payer leaves the checkout page?

Sometimes the payer navigates away from the checkout page to add or remove items. Call the triggerAuthenticationFlow() method every time the checkout page is reloaded. There is internal logic within our SDK that determines whether we require the payer to authenticate via OTP again or restore the session. In either case, the method returns the authenticatedCustomerResult. This also includes a new paymentToken.

I am located outside the US. How can I test Fastlane?

Fastlane is only available to payers in the US. If you are located outside of the US, you need to use a VPN when testing in order to test the payer flows.

Does a Fastlane member have to authenticate with an OTP for every transaction?

A Fastlane member who has authenticated on their device won't receive an OTP for other transactions with the same merchant during the same session. After the session expires, the member must re-authenticate.

Does Fastlane support transactions through MOTO or manual entry?

Currently, Fastlane does not support mail order/telephone order (MOTO) or manual entry transactions.

Best practices

Optimize your buyer experience, Fastlane member experience, integration, and styling.

Buyer experience

Make sure your buyers have the ideal Fastlane experience by following these best practices.

Present the branded PayPal button upstream

You must show the PayPal button upstream in the cart page or alongside the Fastlane email field to ensure consumers have the option to use their PayPal account.

Make email entry the first step

Because Fastlane accounts are looked up by email address, the email address field needs to be the first step of the checkout process. If a profile is found, Fastlane retrieves shipping and payment information for the Fastlane member. If the email comes later in the process, it makes a confusing experience.

Render the Fastlane watermark

Render the Fastlane watermark below any merchant-rendered fields for full consumer transparency. The watermark contains a link where a buyer can go to see the Fastlane terms of service.

Streamline the process

After a registered Fastlane member has been authenticated and the profile information is received, hide any of the member's other payment methods under a single link.

When a buyer enters the OTP, their intent is to use Fastlane. Any additional areas of the UI, such as other payment methods, should be available to give the buyer as many choices as possible. However, keeping the page simple and minimalistic helps the user focus on the transaction.

Member flow

After a Fastlane member authenticates, there are a few best practices that you should implement to further reduce friction during the process:

Integration

Optimize your integration by following these best practices.

Load the Fastlane SDK on your checkout page

Always make sure to load the Fastlane on the onload event of your checkout page. Attempting to load the SDK after a user interacts with the page may cause conversion issues.

Send shipping and billing addresses server-side

While this is always a best practice, it is particularly important in regards to Fastlane. In cases where the buyer adds a shipping address or a new card to their profile, the changes only apply once the token and address info is sent via /v2/checkout/orders.

Call the authentication flow every time the checkout page is refreshed

Call the triggerAuthenticationFlow() method every time the checkout page is reloaded. There is internal logic within our SDK that determines whether we require the buyer to authenticate via OTP again or restore the session. In either case, the method returns the authenticatedCustomerResult. This also includes a new single-use token.

Ensure that Fastlane members can update their stored credentials

Whether you're using our components or rendering a Fastlane profile information yourself, a change button is required.

You can render the ability to edit information in the way that best fits the look and feel of your site checkout. Have the onclick event call the profile.showShippingAddressSelector() or profile.showCardSelector() to launch the necessary modals.

Customize your integration

Use the following configuration parameters, profile method reference types, and style options to customize your Fastlane integration.

Configuration parameters

window.paypal.Fastlane(options);

interface FastlaneOptions {
  shippingAddressOptions: AddressOptions,
  cardOptions: CardOptions,
  styles: StyleOptions
}
/*
 * To restrict the use of Fastlane to specific countries or regions, set
 * allowedLocations to an array containing the countries or regions where Fastlane
 * should be allowed.
 *
 * To allow all regions within a particular country, specify only the country's
 * ISO 3166-1 alpha-2 country code.
 *
 * To allow only specific regions in a country, specify the country's
 * ISO 3166-1 alpha-2 country code, followed by a colon (":"), followed by the
 * name of the region.
 *
 * Examples:
 *
   - [ "US" ] = Allow all regions within the United States
 *
   - [ "US:CA", "US:AZ" ] = Allow in California in Arizona, but nowhere else
 *
   - [ "US:CA", "US:AZ", "FR" ] = Allow in California, Arizona, and France,
 *       but nowhere else
 */
interface AddressOptions {
  // default: empty array = all locations allowed
  allowedLocations: [AddressLocationEnum];
}
Enum AddressLocationEnum {
  {
    ISO - country - code
  } {
    ISO - country - code
  }: {
    ISO - region - code
  }
}
interface CardOptions {
  // default: empty array = all brands allowed
  allowedBrands: [CardBrandEnum];
}
Enum CardBrandEnum {
  VISA
  MASTERCARD
  AMEX
  DINERS
  DISCOVER
  JCB
  CHINA_UNION_PAY
  MAESTRO
  ELO
  MIR
  HIPER
  HIPERCARD
}

type create = (options: FastlaneOptions) => Fastlane;

Fastlane namespace

interface Fastlane {
  identity {
    lookupCustomerByEmail: (email: string) => LookupCustomerResult,
    triggerAuthenticationFlow: (customerContextId: string, options: AuthenticationFlowOptions) => AuthenticatedCustomerResult
  }
  profile {
    showShippingAddressSelector: () => ShowShippingAddressSelectorResult,
    showCardSelector: () => ShowCardSelectorResult,
  }
  setLocale: (locale: string) => void, // options: en_us, es_us, fr_us, zh_us
    FastlaneCardComponent: (options: FastlaneCardComponentOptions) => FastlaneCardComponent,
    FastlanePaymentComponent: (options: FastlanePaymentComponentOptions) => FastlanePaymentComponent,
    FastlaneWatermarkComponent: (options: FastlaneWatermarkOptions) => FastlaneWatermarkComponent
}

LookupCustomerResult

The LookupCustomerResult object type is returned from the identity.lookupCustomerByEmail(email) method.

interface LookupCustomerResult {
  customerContextId: string
}

FastlaneWatermarkComponent

interface FastlaneWatermarkOptions {
  includeAdditionalInfo: boolean
}
interface FastlaneWatermarkComponent {
  render: (container) => null
}

AuthenticatedCustomerResult

The AuthenticatedCustomerResult object type is returned from the identity.triggerAuthenticationFlow() call.

interface AuthenticatedCustomerResult {
  authenticationState: 'succeeded' | 'failed' | 'canceled' | 'not_found';
  profileData: ProfileData;
}
interface ProfileData {
  name: Name;
  shippingAddress: Shipping;
  card: PaymentToken;
}
interface Name = {
  firstName: string;
  lastName: string;
  fullName: string;
};
interface Phone = {
  nationalNumber: string;
  countryCode: string;
};
interface Address = {
  addressLine1: string,
  addressLine2: string,
  adminArea1: string,
  adminArea2: string;
  postalCode: string,
  countryCode: string
  phone: Phone;
};
interface Shipping = {
  name: Name;
  address: Address;
  companyName: string;
}
interface BillingAddress = Address;
interface PaymentToken {
  id: string; // This is the payment paymentToken
  paymentSource: PaymentSource;
}
interface PaymentSource {
  card: CardPaymentSource;
}
interface CardPaymentSource {
  brand: string;
  expiry: string; // "YYYY-MM"
  lastDigits: string; // "1111"
  name: string;
  billingAddress: Address;
}

Profile method reference types

interface ShowShippingAddressSelectorResult {
  selectionChanged: boolean;
  selectedAddress: Address;
}
interface ShowCardSelectorResult {
  selectionChanged: boolean;
  selectedCard: PaymentToken;
}

FastlaneCardComponent

The FastlaneCardComponent uses hosted card fields. The resulting interface is a subset of the card fields interface.

The instance of a FastlaneCardComponent can be created using:

const fastlaneCardComponent = await fastlane.FastlaneCardComponent({
  ...
})
fastlaneCardComponent.render("#card-container")

FastlaneCardComponent reference types:

type FastlaneCardComponent = (options: FastlaneCardComponentOptions) => FastlaneCardComponent;
interface FastlaneCardComponent {
  render: (container) => FastlaneCardComponent;
  getPaymentToken: async (options: PaymentTokenOptions) => PaymentToken;
}
interface FastlaneCardComponentOptions {
  styles: StyleOptions;
  fields: {
    Field
  };
}
interface Field {
  placeholder: string;
  prefill: string;
  enabled: boolean;
}
interface PaymentTokenOptions {
  billingAddress: Address;
  cardholderName: Name;
}

Card field configurations

You can configure the card fields in the FastlaneCardComponent or FastlanePaymentComponent when initializing the components:

const styles: {};
const fields: {
  number: {
    placeholder: "Number",
  },
  phoneNumber: {
    prefill: "555-555-5555"
  }
}
}

fastlane.FastlaneCardComponent({
  styles,
  fields
}).render(elem);
fastlane.FastlanePaymentComponent({
  styles,
  fields
}).render(elem);

You can prefill both FastlaneCardComponent and FastlanePaymentComponent.

Style options and guidelines

Colors can be any value that CSS allows in hex values, RGB, RGBA, and color names.

interface StyleOptions {
  root: {
    backgroundColor: string,
    errorColor: string,
    fontFamily: string,
    textColorBase: string,
    fontSizeBase: string,
    padding: string,
    primaryColor: string,
  },
  input: {
    backgroundColor: string,
    borderRadius: string,
    borderColor: string,
    borderWidth: string,
    textColorBase: string,
    focusBorderColor: string,
  },
}

Design guidance

When styling the Fastlane components to match the look and feel of your checkout page, here are some guidelines to provide an accessible and transparent experience to your payer:

Payment component UI

See payment component UI values

Load card assets

Use the following image URLs to load card assets. These enable users to see the branded image of their card.

See also

Related documentation: