Setting up Express Checkout

Overview

To enable the express checkout, SCAYLE offers a simplified integration through a web component. With only one-time straightforward implementation, you can offer your customers a range of payment methods while managing important aspects such as access token handling and cookie consent.

Compatibility

Can be integrated in desktop, mobile web and app.

Key Features

Token Handling

The web component offers an option to handle access token refresh to ensure a secure and uninterrupted payment process. For users who have been logged in for a long period, the component checks if the access token has expired and informs the storefront. If so, the store front can prompt users to re-login to continue with the payment, preventing session disruptions while ensuring a secure transaction.

Cookie Consent ¹Handling

If you want to handle cookie consent for your shop through the Express Checkout, our web component provides an option to receive consent status directly from the shop.

• Case 1: Returning Customers

When customers first create an account or make a purchase, they may have already agreed to the shop's general cookies. However, because the express checkout uses additional cookies that weren’t included in the original consent, the shop can ask customers for permission to use these extra cookies. This can be done when the customer selects the express payment method in the basket.

• Case 2: New / Guest Customers

For new and guest users, the shop can include the express checkout cookies in the general cookie consent prompt displayed on the homepage. This ensures that consent for the express cookies is obtained before the user reaches the basket page. However, if the user rejects the cookies or closes the consent window, the shop can prompt the user to agree to the express cookies again when they select the express payment method in the basket.

• How the web component behaves if no consent is given

Each payment provider has its own method for setting cookies and may store different types of data. We recommend that tenants reach out to their payment providers for more information and a thorough legal assessment to ensure full compliance.

For example, some providers may set cookies as soon as their SDK is initialized to render the payment button on the basket page. Our web component is designed to prevent the setting of non-consented cookies when loading the express payment methods. To achieve this, we have tailored solutions depending on the specific payment provider in use.

Please reach out to your SCAYLE Account Manager for more information on this solution.

Mobile App Handling

The web component can be used in mobile apps with a static button that triggers the payment SDK in a web view.

Step 1: Payment Configuration

Contact your SCAYLE Account Manager to configure express payment methods for your shop. Here’s an overview:

PayPal Express

SCAYLE offers PayPal wallet with the following capture types:

• Instant capture - when the money gets debited from the customer's account upon order confirmation.
• Delayed capture - the money gets debited from the customer's account once the items are shipped.

You have the flexibility to configure any of them for the express checkout. to use the same capture type as the regular checkout or set a different capture type for the express flow. Below the possibilities:

Klarna Express

Klarna offers a variety of payment options depending on the market, such as Pay Now, Pay Later, and Pay in 3 (installments). The Express Checkout supports all of these, but to render the Klarna button on the basket page, you must define a default payment method key.

The pre-selection of the payment option is fully managed by Klarna, based on the shopper’s account history and behavior. SCAYLE has no control over which option appears first in the Klarna widget.

When the customer logs into their Klarna account, they will be shown all available Klarna payment methods applicable to their market — as long as the basket total falls within the limits defined in the existing Klarna configuration from the regular checkout.

Klarna Payment Options Update

If the customer selects a different Klarna option during the express checkout flow (i.e. one that differs from the default key), SCAYLE automatically updates this selection in the backend during the Review Page step.

Example: You have configured Express Checkout to use Klarna Pay Later as the default key. In the customer's Klarna account, all three Klarna options — Pay Now, Pay Later, and Pay in 3 — are available.

When the customer opens the Klarna widget and selects Klarna Pay Now instead of the default, here is what happens:

1. After payment authorization, the user is redirected to the Review Page.
2. The checkout backend detects the updated Klarna selection and updates the transaction accordingly.
3. The backend then validates whether the basket total meets the min/max limits defined for the newly selected Klarna method.

If the basket is within limits: the user can complete the checkout, and is redirected directly to the Order Success Page with no additional widget interaction.

If the basket is out of constraints: when the user clicks the "Checkout" button, the Klarna widget reopens, allowing them to select a different valid payment option.

This flow ensures full flexibility for the customer, while maintaining consistency with your shop’s Klarna configuration.

Step 2: Technical Implementation

Follow these steps to start the integration:

1. Web Component Integration
   1. Loading the JavaScript bundle
   2. Initialising the web component
   3. Attributes
   4. Events
2. User Consent Handling for GDPR Compliance
3. Review Page
   1. Overview
   2. Attributes
4. Errors Handling

Web Component Integration

How to integrate the express checkout web component into your shop frontend

Load the Checkout bundle

To begin, insert the following <script> tag into the <head> of your basket page. This script loads the Checkout pre-loader, which includes both the regular checkout and Express Checkout components, along with required assets (CSS, images, etc.):

html

Copy

Add the Express Checkout Component

Place the <scayle-express-checkout> tag in your basket page where you want the Express Checkout button to appear.

Example:

html

Copy

Attributes

The express component relies on a set of attributes that control its behavior and data handling. Some of these attributes are mandatory for the component to function correctly (e.g., jwt, device, and basket-total), while others are optional.

As outlined in the feature scope, the Express Checkout does work for unauthenticated (guest) users, therefore a valid jwt must be provided. Find out how to generate the token here.

The access-token is optional and mainly used for pre-filling customer data in case of logged users — it is not required for guest flows. Find out how to generate the token here.

Events

The express component communicates back with the storefront using events. These events allow you to handle specific scenarios such as token refresh, consent updates, user redirection after payment, and debugging. Some of these events are mandatory to implement, as they are essential for Express Checkout to function correctly. Others are optional and can be used to enhance the customer experience or add additional monitoring and fallback logic.

Below is an overview of the events emitted by the component:

Express button translation

The express checkout buttons may display text such as "Checkout" or "Pay with" alongside the provider logo, as shown here.

• The Klarna button text cannot be configured and is consistent across all tenants and locales globally. Below a list of languages supported and respective translations:

• The PayPal button text is sourced from the PayPal JS SDK and can be partially customized using the SDK’s configuration parameters (such as the label field). More details can be found in the provider's technical documentation.

Handling User Consent for GDPR Compliance

User consent is mandatory to mount most payment SDKs and the express method will not work until this value of consent attribute is changed to true .

If the value of attribute is set to false , any attempt of your customer to proceed to Express Checkout will trigger the consent-missing event.

The storefront is responsible for handling the consent-missing event and prompting the user to accept the necessary cookies. Once consent is granted, the storefront must update the consent attribute on the web component. The component will then automatically load the relevant payment SDK, allowing the user to continue.

If you do not intend to implement consent handling, you can simply pass "true" for all configured providers in the consent attribute from the start.

Order Review Page

This section details the implementation of the express checkout review page. It is based on the standard checkout web component.

Attributes

Errors handling

Like any other payment method in the checkout, the express checkout flow may encounter negative scenarios, such as payment declines or invalid address entries on the payment provider's page, among others. The web component will capture these errors and send them to the storefront through the express-error event, allowing the tenant to decide the appropriate redirection for the user based on the specific issue encountered and desired user experience.

Examples of redirection:

• Order Review Page: All the cases in which, after submitting the payment in the provider page/widget, the user can still have a valid payment/order confirmation attempt. I.e.: incorrect shipping address provided.
• Regular Checkout Page: All the cases in which the user cannot confirm the payment and/or the order in the review page. I.e.: Declined/failed payment in the widget, declined/failed payment upon order confirmation, device not allowed for express checkout, etc.
• Basket Page: All the cases in which the user could not submit the payment in the provider's page/widget. I.e.: user closed/exited the payment widget/page.

The error might be returned from an API response or from the payment widget itself. Depending on the source, the web component will send status codes and/or error messages. Below is a list of the errors and the possible reasons.

API errors

Widget and SDK load errors

Configure Dynamic Fields in the Review Page

The Review Page leverages the same dynamic field configuration used in the regular checkout—no separate structure is introduced. Instead, visibility is controlled using the "alwaysShowOnReviewPage" flag, which gives you full flexibility over which fields should appear in the final step, helping improve clarity and transparency for users.

For general instructions on how to configure dynamic fields, please refer to the documentation here.

The behavior is as follows:

Examples of Dynamic Field Configuration on the Review Page

Example 1 - Mandatory Field – Automatically Shown on Review Page

If a field is both enabled and required, it will automatically appear on the Review Page—no extra flag needed.

Without alwaysShowOnReviewPage:

json

Copy

With alwaysShowOnReviewPage (optional but valid):

json

Copy

Example 2 - Non-Mandatory Field – Must Use alwaysShowOnReviewPage

If the field is optional, you must set alwaysShowOnReviewPage: true to display it on the Review Page.

json

Copy

Explanation:

• enabled: true → field is available in checkout
• required: false → user is not forced to fill it
• alwaysShowOnReviewPage: true → ensures it appears in the Review Page

Example 3 - Checkboxes: Optional Newsletter Signup & Mandatory Terms

json

Copy

Explanation:

• newsletterSignUp → optional checkbox, shown because of alwaysShowOnReviewPage: true
• termsAndPrivacy → required checkbox, automatically shown due to required: true

Example 4 - Text Field: Optional Terms & Privacy Text

json

Copy

Explanation:

This displays the Terms & Privacy text on the Review Page even though it is not required, thanks to the alwaysShowOnReviewPage flag.

Troubleshooting