Pre-selecting PayPal via Store Builder Library

Last modified April 15, 2019

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

Using Store Builder Library (SBL), you can optionally create a button that launches PayPal directly, completely bypassing the initial Popup Storefront or Web Storefront interface, under certain conditions. This streamlines the purchase process, makes it more familiar for customers who frequently make purchases using PayPal, and should improve conversion rates for such customers.


In order to pre-select PayPal as the payment method, your page must load SBL version 0.8.0 or later.

Conditions Required to Pre-Select PayPal

Under certain circumstances, pre-selecting PayPal still results in the normal checkout flow (with a Popup Storefront or a Web Storefront). When this happens with a Popup Storefront, PayPal is selected as the payment method.

The FastSpring Storefront cannot be skipped in any of the following circumstances:

  • If the Storefront targeted via the data-storefront attribute when you load SBL allows customers the option to opt out of having FastSpring save the payment details (thus creating a manual renewal subscription), then the Storefront is displayed to allow the customer to select or clear that check box. To control this setting:
    • For Web Storefronts:  Storefronts → Web Storefronts → SETTINGS → General Settings → Allow Auto/Manual subscription renewal
    • For Popup Storefronts:  Storefronts → Popup Storefronts → SETTINGS → Checkout → Auto/Manual subscription renewal
  • If the order country is located in the European Union, then FastSpring is required by GDPR to collect proactive authorization from the customer to store the customer's personal information, so the Storefront is displayed to allow the customer to select the I agree with FastSpring terms of service and privacy policy check box.
  • If FastSpring does not support PayPal payments in the order country (e.g. in Turkey), then the Storefront is displayed as normal, with no PayPal option available.

Methods of Pre-Selecting PayPal

To create a button that attempts to skip the FastSpring Storefront and directs the customer straight to the PayPal login, use one of the following approaches:


If the cart is empty when attempting any of these approaches, the behavior is the same as the normal checkout process - a silent response code 400 will be returned and nothing further will happen.

Determining When to Display a Separate PayPal Button


If you attempt to pre-select PayPal as the payment method when PayPal is not available, SBL will return a silent response of 400 - invalid payment method.

There are two ways you can identify whether or not PayPal is currently available for the order session based on the contents of the cart, the order country, and other factors. Using either of the following methods, you can hide or show a dedicated "Pay with PayPal" button, according to PayPal's actual current availability.

Using the smartdisplay Directive

If you plan to use the markup directive data-fsc-action="PaypalCheckout" to create a dedicated PayPal button, you can add a couple of directives to the button so that it will only show when PayPal is currently available.

Adding both data-fsc-order-paypal-available and data-fsc-smartdisplay to your button will cause the element to be hidden when PayPal is not available, and to be displayed when it is available.  Here is an example of a basic button (this could be styled with CSS, etc.):

<button data-fsc-action="PaypalCheckout" data-fsc-order-paypal-available data-fsc-smartdisplay>Check Out with PayPal</button> 

Parsing the Order Object Response

The order object response includes an array named availablePaymentMethods that lists each of the payment methods that are currently available. A single value is returned for each available payment method, as in the following example:


If "paypal" is included in the array, you can display a button that will launch PayPal directly. If "paypal" is not included in the array, you may choose to suppress / hide the button.