Fastlane reference

DocsCurrent

Last updated: Feb 6th, 9:42am

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 client credentials may not be fully provisioned for Fastlane. Contact 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 and complete the order. The payment should be processed successfully with the new card.

No payment token returned

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

Undefined methods returned

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

If Fastlane is disabled, the Fastlane client SDK falls back to the guest experience without the option to create a Fastlane profile, ensuring no interruption to buyers.

FAQs

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

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 calling window.paypal.fastlane.create(), you can pass a list of allowed locations using the addressOptions object.

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

If the payer navigates away from the checkout page, call the triggerAuthenticationFlow() method when the page reloads. The SDK determines whether the payer must authenticate via OTP again or if the session should be restored. The method returns the authenticatedCustomerResult, which 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 outside the US, use a VPN 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 additional transactions with the same merchant during the same session. After the session expires, re-authentication is required.

Does Fastlane support transactions through MOTO or manual entry?

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

Ensure buyers have the best Fastlane experience by following these best practices.

Present the branded PayPal button upstream

Display the PayPal button on the cart page or alongside the Fastlane email field to provide buyers the option to use their PayPal account.

Make email entry the first step

Fastlane accounts are looked up by email address, so the email field must be the first step of checkout. If a profile is found, Fastlane retrieves shipping and payment details. If email is requested later in the process, it can create a confusing experience.

Render the Fastlane watermark

Display the Fastlane watermark below merchant-rendered fields for transparency. The watermark includes a link to the Fastlane terms of service.

Streamline the process

Once a Fastlane member is authenticated and their profile is retrieved, simplify the UI by hiding other payment methods under a single link.

When a buyer enters the OTP, they intend to use Fastlane. Provide access to other payment methods but maintain a minimalistic UI to keep the focus on completing the transaction.

Member Flow

After a Fastlane member authenticates, implement these best practices to reduce friction:

Direct users to the order review page or equivalent.

Ensure the least expensive shipping option is pre-selected.

Provide a change button for the shipping address, which should call showAddressSelector() to allow buyers to update or add a new address.

Provide a change button for the payment method, calling showCardSelector() to allow selection or addition of a new card.

For specific use cases, such as adding a gift message, direct returning users to the relevant page.

Integration

Optimize your integration with these best practices.

Load the Fastlane SDK on your checkout page

Always load the Fastlane SDK during the onload event of the checkout page. Delayed SDK loading may cause conversion issues.

Send shipping and billing addresses server-side

Ensure shipping and billing address updates apply correctly by passing them via /v2/checkout/orders. This is especially important when users add new addresses or payment methods.

Call authentication flow on checkout page refresh

Invoke triggerAuthenticationFlow() each time the checkout page reloads. The SDK determines whether re-authentication via OTP is required or if the session can be restored. This method returns the authenticatedCustomerResult, including a new single-use token.

Ensure that Fastlane members can update stored credentials

Ensure users can edit their profile details. Use a change button that calls profile.showShippingAddressSelector() or profile.showCardSelector() to launch modals for updating information.

Customize your integration

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

Configuration Parameters

To initialize Fastlane, use the following method:

window.paypal.Fastlane(options);

1interfaceFastlaneOptions{
2shippingAddressOptions:AddressOptions,
3cardOptions:CardOptions,
4styles:StyleOptions
5}
6/*
7 * To restrict the use of Fastlane to specific countries or regions, set
8 * allowedLocations to an array containing the countries or regions where Fastlane
9 * should be allowed.
10 *
11 * To allow all regions within a particular country, specify only the country's
12 * ISO 3166-1 alpha-2 country code.
13 *
14 * To allow only specific regions in a country, specify the country's
15 * ISO 3166-1 alpha-2 country code, followed by a colon (":"), followed by the
16 * name of the region.
17 *
18 * Examples:
19 *   - [ "US" ] = Allow all regions within the United States
20 *   - [ "US:CA", "US:AZ" ] = Allow in California in Arizona, but nowhere else
21 *   - [ "US:CA", "US:AZ", "FR" ] = Allow in California, Arizona, and France,
22 *       but nowhere else
23 */
24interfaceAddressOptions{
25// default: empty array = all locations allowed
26allowedLocations:[AddressLocationEnum];
27}
28EnumAddressLocationEnum{
29{
30ISO- country - code
31}{
32ISO- country - code
33}:{
34ISO- region - code
35}
36}
37interfaceCardOptions{
38// default: empty array = all brands allowed
39allowedBrands:[CardBrandEnum];
40}
41EnumCardBrandEnum{
42VISA
43MASTERCARD
44AMEX
45DINERS
46DISCOVER
47JCB
48CHINA_UNION_PAY
49MAESTRO
50ELO
51MIR
52HIPER
53HIPERCARD
54}

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

Fastlane namespace

1interface Fastlane {
2  identity {
3    lookupCustomerByEmail: (email: string) => LookupCustomerResult,
4    triggerAuthenticationFlow: (customerContextId: string, options: AuthenticationFlowOptions) => AuthenticatedCustomerResult
5  }
6  profile {
7    showShippingAddressSelector: () => ShowShippingAddressSelectorResult,
8    showCardSelector: () => ShowCardSelectorResult,
9  }
10  setLocale: (locale: string) => void, // options: en_us, es_us, fr_us, zh_us
11    FastlaneCardComponent: (options: FastlaneCardComponentOptions) => FastlaneCardComponent,
12    FastlanePaymentComponent: (options: FastlanePaymentComponentOptions) => FastlanePaymentComponent,
13    FastlaneWatermarkComponent: (options: FastlaneWatermarkOptions) => FastlaneWatermarkComponent
14}

LookupCustomerResult

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

1interface LookupCustomerResult {
2  customerContextId: string
3}

FastlaneWatermarkComponent

1interface FastlaneWatermarkOptions {
2  includeAdditionalInfo: boolean
3}
4interface FastlaneWatermarkComponent {
5  render: (container) => null
6}

AuthenticatedCustomerResult

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

1interface AuthenticatedCustomerResult {
2  authenticationState: 'succeeded' | 'failed' | 'canceled' | 'not_found';
3  profileData: ProfileData;
4}
5interface ProfileData {
6  name: Name;
7  shippingAddress: Shipping;
8  card: PaymentToken;
9}
10interface Name = {
11  firstName: string;
12  lastName: string;
13  fullName: string;
14};
15interface Phone = {
16  nationalNumber: string;
17  countryCode: string;
18};
19interface Address = {
20  addressLine1: string,
21  addressLine2: string,
22  adminArea1: string,
23  adminArea2: string;
24  postalCode: string,
25  countryCode: string
26  phone: Phone;
27};
28interface Shipping = {
29  name: Name;
30  address: Address;
31  companyName: string;
32}
33interface BillingAddress = Address;
34interface PaymentToken {
35  id: string; // This is the payment paymentToken
36  paymentSource: PaymentSource;
37}
38interface PaymentSource {
39  card: CardPaymentSource;
40}
41interface CardPaymentSource {
42  brand: string;
43  expiry: string; // "YYYY-MM"
44  lastDigits: string; // "1111"
45  name: string;
46  billingAddress: Address;
47}

Profile method reference types

1interface ShowShippingAddressSelectorResult {
2  selectionChanged: boolean;
3  selectedAddress: Address;
4}
5interface ShowCardSelectorResult {
6  selectionChanged: boolean;
7  selectedCard: PaymentToken;
8}

FastlaneCardComponent

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

An instance of a FastlaneCardComponent can be created using:

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

FastlaneCardComponent reference types:

1type FastlaneCardComponent = (options: FastlaneCardComponentOptions) => FastlaneCardComponent;
2interface FastlaneCardComponent {
3  render: (container) => FastlaneCardComponent;
4  getPaymentToken: async (options: PaymentTokenOptions) => PaymentToken;
5}
6interface FastlaneCardComponentOptions {
7  styles: StyleOptions;
8  fields: {
9    Field
10  };
11}
12interface Field {
13  placeholder: string;
14  prefill: string;
15  enabled: boolean;
16}
17interface PaymentTokenOptions {
18  billingAddress: Address;
19  cardholderName: Name;
20}

Card Field Configurations

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

1const styles: {};
2const fields: {
3  number: {
4    placeholder: "Number",
5  },
6  phoneNumber: {
7    prefill: "555-555-5555"
8  }
9}
10} 
11
12fastlane.FastlaneCardComponent({
13  styles,
14  fields
15}).render(elem);
16fastlane.FastlanePaymentComponent({
17  styles,
18  fields
19}).render(elem);

You can prefill both FastlaneCardComponent and FastlanePaymentComponent.

See Available Card Fields

Name	Type	Attributes	Description
`number`	field	Optional	A field for the card number.
`expirationDate`	field	Optional	A field for expiration date in `MM/YYYY` or `MM/YY` format. This should not be used with the `expirationMonth` and `expirationYear` properties.
`expirationMonth`	field	Optional	A field for expiration month in `MM` format. This should be used with the `expirationYear` property.
`expirationYear`	field	Optional	A field for expiration year in `YYYY` or `YY` format. This should be used with the `expirationMonth` property.
`cvv`	field	Optional	A field for a 3 or 4-digit card verification code (like CVV or CID). If creating a CVV-only payment token to verify a card stored in your vault, omit all other fields.
`postalCode`	field	Optional	A field for the postal or region code.
`cardholderName`	field	Optional	A field for the cardholder name on the payer's credit card.
`phoneNumber`	field	Optional	A field for the payer's phone number.

Style options and guidelines

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

1interface StyleOptions {
2  root: {
3    backgroundColor: string,
4    errorColor: string,
5    fontFamily: string,
6    textColorBase: string,
7    fontSizeBase: string,
8    padding: string,
9    primaryColor: string,
10  },
11  input: {
12    backgroundColor: string,
13    borderRadius: string,
14    borderColor: string,
15    borderWidth: string,
16    textColorBase: string,
17    focusBorderColor: string,
18  },
19}

Design Guidance

When styling the Fastlane components to match your checkout page, follow these guidelines to ensure an accessible and transparent experience for your payer:

Ensure there is adequate contrast between backgroundColor and textColor to keep all text, especially legal text under the opt-in, clear and legible. If the contrast ratio is below 4.5:1, PayPal automatically sets the contrast to the default values shown in the table below.

Ensure adequate contrast between borderColor, which determines the consent toggle color, and backgroundColor.

Note: All Fastlane integrations must conform to WCAG levels A and AA. If the color of the legal text and toggle button is not distinguishable from the text and background, the Fastlane component colors will revert to the default.

Payment component UI

See Payment Component UI Values

Value	Description	Default	Guidance and Thresholds
`root.backgroundColor`	The background color of the components.	`#ffffff`	May be any valid CSS color. No transparency allowed.
`root.errorColor`	The color of errors in the components.	`#D9360B`	May be any valid CSS color. No transparency allowed.
`root.fontFamily`	The font family used throughout the UI.	`PayPal-Open`	Must be one of: Arial, Verdana, Tahoma, Trebuchet MS, Times New Roman, Georgia, Garamond, Courier New, Brush Script MT.
`root.fontSizeBase`	The base font size. Increasing this value changes text size in UI components.	`16px` (Min: `13px`, Max: `24px`)
`root.textColorBase`	The text color used across all text outside of inputs.	`#01080D`	May be any valid CSS color. No transparency allowed.
`input.borderRadius`	The border radius used for the email field.	`0.25em` (Min: `0px`, Max: `32px`)
`input.borderColor`	The border color of the email field.	`#DADDDD`	May be any valid CSS color. No transparency allowed.
`input.focusBorderColor`	The border color of the email field when focused.	`#0057FF`	May be any valid CSS color. No transparency allowed.
`input.borderWidth`	The width of the input borders.	`1px` (Max: `5px`)	Default size is 1px.
`input.textColorBase`	The text color used for text within input fields.	`#01080D`	May be any valid CSS color. No transparency allowed.

Load Card Assets

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

Card Brand	Image URL
Amex	Amex Logo
Diners Club	Diners Club Logo
Discover	Discover Logo
JCB	JCB Logo
Mastercard	Mastercard Logo
Union Pay	Union Pay Logo
Visa	Visa Logo