# Fastlane reference (/v5/fastlane/reference) Troubleshoot, read our FAQs, follow best practices, and customize your integration. ## Troubleshooting [#troubleshooting] The following are common issues and steps to take to resolve them: ### Authorization error while initializing Fastlane [#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 [#fastlane-member-doesnt-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 [#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 [#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 [#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? [#will-fastlane-work-if-i-save-a-payers-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? [#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? [#what-if-the-payers-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? [#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? [#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? [#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? [#does-fastlane-support-transactions-through-moto-or-manual-entry] Fastlane does not support mail order/telephone order (MOTO) or manual entry transactions. ## Best practices [#best-practices] Optimize your buyer experience, Fastlane member experience, integration, and styling. ### Buyer Experience [#buyer-experience] Ensure buyers have the best Fastlane experience by following these best practices. #### Present the branded PayPal button upstream [#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 [#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 [#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 [#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 [#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 [#integration] Optimize your integration with these best practices. #### Load the Fastlane SDK on your checkout page [#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 [#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 [#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-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 [#customize-your-integration] Use the following configuration parameters, profile method reference types, and style options to customize your Fastlane integration. ### Configuration Parameters [#configuration-parameters] To initialize Fastlane, use the following method: `window.paypal.Fastlane(options);` ```text lineNumbers interfaceFastlaneOptions{ 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 */ interfaceAddressOptions{ // default: empty array = all locations allowed allowedLocations:[AddressLocationEnum]; } EnumAddressLocationEnum{ { ISO- country - code }{ ISO- country - code }:{ ISO- region - code } } interfaceCardOptions{ // default: empty array = all brands allowed allowedBrands:[CardBrandEnum]; } EnumCardBrandEnum{ CHINA_UNION_PAY } ``` ```text lineNumbers type create=(options:FastlaneOptions)=>Fastlane; ``` ## Fastlane namespace [#fastlane-namespace] ```text lineNumbers 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 [#lookupcustomerresult] The `LookupCustomerResult` object type is returned from the `identity.lookupCustomerByEmail(email)` method. ```text lineNumbers interface LookupCustomerResult { customerContextId: string } ``` ### FastlaneWatermarkComponent [#fastlanewatermarkcomponent] ```text lineNumbers interface FastlaneWatermarkOptions { includeAdditionalInfo: boolean } interface FastlaneWatermarkComponent { render: (container) => null } ``` ### AuthenticatedCustomerResult [#authenticatedcustomerresult] The `AuthenticatedCustomerResult` object type is returned from the `identity.triggerAuthenticationFlow()` call. ```text lineNumbers 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 [#profile-method-reference-types] ```text lineNumbers interface ShowShippingAddressSelectorResult { selectionChanged: boolean; selectedAddress: Address; } interface ShowCardSelectorResult { selectionChanged: boolean; selectedCard: PaymentToken; } ``` ### FastlaneCardComponent [#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: ```text lineNumbers const fastlaneCardComponent = await fastlane.FastlaneCardComponent({ ... }) fastlaneCardComponent.render("#card-container") ``` `FastlaneCardComponent` reference types: ```text lineNumbers 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 [#card-field-configurations] You can configure the card fields in the `FastlaneCardComponent` or `FastlanePaymentComponent` when initializing the components. ```text lineNumbers 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`. ### See Available Card Fields [#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 [#style-options-and-guidelines] Colors can be any value that CSS allows in hex values, RGB, RGBA, and color names. ```text lineNumbers 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 [#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`. > **Info:** **Note:** All Fastlane integrations must conform to > [WCAG levels A and AA](https://www.w3.org/TR/WCAG21/,). > 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 [#payment-component-ui] ### See Payment Component UI Values [#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 [#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](https://www.paypalobjects.com/fastlane-v1/assets/cc_amex_light.81e1.svg) | | Diners Club | [Diners Club Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_dinersclub_light.354d.svg) | | Discover | [Discover Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_discover_light.85a5.svg) | | JCB | [JCB Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_jcb_light.6fb4.svg) | | Mastercard | [Mastercard Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_mastercard_light.1621.svg) | | Union Pay | [Union Pay Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_unionpay_light.1519.svg) | | Visa | [Visa Logo](https://www.paypalobjects.com/fastlane-v1/assets/cc_visa_light.0a3a.svg) | ## See also [#see-also] Related documentation: > **Info:** [Integrate Fastlane](/platforms/checkout/fastlane) > > Use our ready-made quickstart integration or customize form fields with our flexible integration. > **Info:** [Upgrade to Fastlane](/v5/fastlane/upgrade) > > Upgrade existing PayPal and card integrations to use Fastlane. > **Info:** [Get started](/checkout) > > Set up your development environment to integrate Fastlane.