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 reference
Last updated: August 1st 2024, @ 11:23:55 am
Troubleshoot, read our FAQs, follow best practices, and customize your integration.
Troubleshooting
The following are common issues and steps to take to resolve them.
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.
If FastlaneCardComponent.getPaymentToken()
doesn't return a token, ensure that you're passing all required parameters in the correct format.
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
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.
A paymentToken
is valid for 3 hours from the time of issuance.
When you initially call window.paypal.fastlane.create()
, you have the option of passing in a list of allowed locations using the addressOptions
object.
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
.
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.
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.
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.
Make sure your buyers have the ideal Fastlane experience by following these best practices.
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.
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 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.
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.
After a Fastlane member authenticates, there are a few best practices that you should implement to further reduce friction during the process:
- Put the user at the order review page, or your site's equivalent.
- Ensure the least expensive shipping option is automatically selected.
- Render a change button for the shipping address. That change button should call the
showAddressSelector()
method of the client SDK. This invokes the shipping address selector allowing the buyer to select from shipping addresses or add a new one. - Render a change button for the card being used for the purchase. That change button should call the
showCardSelector()
method of the client SDK. This invokes the card selector, allowing the buyer to select from other cards or add a new one to their profile. - For other use cases, such as adding a gift message, you can direct a return user to land on that specific page.
Optimize your integration by following these best practices.
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.
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 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.
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.
window.paypal.Fastlane(options);
1interface FastlaneOptions {2 shippingAddressOptions: AddressOptions,3 cardOptions: CardOptions,4 styles: StyleOptions5}6/*7 * To restrict the use of Fastlane to specific countries or regions, set8 * allowedLocations to an array containing the countries or regions where Fastlane9 * should be allowed.10 *11 * To allow all regions within a particular country, specify only the country's12 * ISO 3166-1 alpha-2 country code.13 *14 * To allow only specific regions in a country, specify the country's15 * ISO 3166-1 alpha-2 country code, followed by a colon (":"), followed by the16 * name of the region.17 *18 * Examples:19 * - [ "US" ] = Allow all regions within the United States20 * - [ "US:CA", "US:AZ" ] = Allow in California in Arizona, but nowhere else21 * - [ "US:CA", "US:AZ", "FR" ] = Allow in California, Arizona, and France,22 * but nowhere else23 */24interface AddressOptions {25 // default: empty array = all locations allowed26 allowedLocations: [AddressLocationEnum];27}28Enum AddressLocationEnum {29 {30 ISO - country - code31 } {32 ISO - country - code33 }: {34 ISO - region - code35 }36}37interface CardOptions {38 // default: empty array = all brands allowed39 allowedBrands: [CardBrandEnum];40}41Enum CardBrandEnum {42 VISA43 MASTERCARD44 AMEX45 DINERS46 DISCOVER47 JCB48 CHINA_UNION_PAY49 MAESTRO50 ELO51 MIR52 HIPER53 HIPERCARD54}
1type create = (options: FastlaneOptions) => Fastlane;
1interface Fastlane {2 identity {3 lookupCustomerByEmail: (email: string) => LookupCustomerResult,4 triggerAuthenticationFlow: (customerContextId: string, options: AuthenticationFlowOptions) => AuthenticatedCustomerResult5 }6 profile {7 showShippingAddressSelector: () => ShowShippingAddressSelectorResult,8 showCardSelector: () => ShowCardSelectorResult,9 }10 setLocale: (locale: string) => void, // options: en_us, es_us, fr_us, zh_us11 FastlaneCardComponent: (options: FastlaneCardComponentOptions) => FastlaneCardComponent,12 FastlanePaymentComponent: (options: FastlanePaymentComponentOptions) => FastlanePaymentComponent,13 FastlaneWatermarkComponent: (options: FastlaneWatermarkOptions) => FastlaneWatermarkComponent14}
The LookupCustomerResult object type is returned from the identity.lookupCustomerByEmail(email)
method.
1interface LookupCustomerResult {2 customerContextId: string3}
1interface FastlaneWatermarkOptions {2 includeAdditionalInfo: boolean3}4interface FastlaneWatermarkComponent {5 render: (container) => null6}
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: string26 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 paymentToken36 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}
1interface ShowShippingAddressSelectorResult {2 selectionChanged: boolean;3 selectedAddress: Address;4}5interface ShowCardSelectorResult {6 selectionChanged: boolean;7 selectedCard: PaymentToken;8}
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:
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 Field10 };11}12interface Field {13 placeholder: string;14 prefill: string;15 enabled: boolean;16}17interface PaymentTokenOptions {18 billingAddress: Address;19 cardholderName: Name;20}
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}1112fastlane.FastlaneCardComponent({13 styles,14 fields15}).render(elem);16fastlane.FastlanePaymentComponent({17 styles,18 fields19}).render(elem);
You can prefill both FastlaneCardComponent
and FastlanePaymentComponent
.
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 3 or 4-digit card verification code (like CVV or CID). If you wish to create a CVV-only payment token to verify a card already stored in your vault, omit all other fields to only collect CVV. |
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 cardholder name on the payer's credit card. |
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}
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:
- Ensure that there is adequate contrast between the
backgroundColor
andtextColor
to ensure that all text, especially the legal text under the opt-in, is clear and legible. If the contrast ratio between the two is not 4.5:1, PayPal automatically sets the contrast to the default values in the following table. - Ensure there is adequate contrast between the
borderColor
, which drives the consent toggle coloring, and thebackgroundColor
.
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 the following:
|
root.fontSizeBase | The base font size. Increasing this value changes the text size of all text within the UI components. | 16px , 13px min, 24px max | |
root.textColorBase | The text color used across all text outside of inputs. | #01080D | May be any valid CSS color. No transparency allowed. |
root.padding | The padding between content and borders. | 4px , 0px min, 10px max | |
root.primaryColor | This value sets the default for the checkbox for billing address, and the link for the "change", the toggle primary color, and the legal links for privacy and terms. | #0057FF | May be any valid CSS color. No transparency allowed. |
input.backgroundColor | The background color of the inputs within the components. | #ffffff | May be any valid CSS color. No transparency allowed. |
input.borderRadius | The border radius used for the email field. | 0.25em , 0px min, 32px max | |
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 , 5px max | 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. |
Use the following image URLs to load card assets. These enable users to see the branded image of their card.
See also
Related documentation:
Use our ready-made quickstart integration or customize form fields with our flexible integration.
Upgrade existing PayPal and card integrations to use Fastlane.
Set up your development environment to integrate Fastlane.