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 Key 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 Key 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 different payment options depending on the market, including Pay Now, Pay Later, and Pay in 3 (installments). While the express checkout supports all of these options, you must select a default payment option to render the Klarna button on the basket page. This default option will be pre-selected when the customer logs into their Klarna account. Within the Klarna widget, customers will be shown all available payment options for their market, based on the limits defined for the minimum and maximum order value.

If the customer changes the payment option in the widget, upon order confirmation in the order review page, the payment method name will be updated in the order details.

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

Loading the JavaScript bundle

To begin, insert the following JavaScript snippet into the head element of desired page, to load the Checkout bundle:

html

Copy

<script
  src="https://${tenant-space}.checkout.api.scayle.cloud/frontend/express/js?appId=${shopId}"
  defer
></script>

This script registers the web component with the browser and loads necessary assets (CSS, images).

Initialising the web component

To initialise and display the web component, add the <scayle-express-checkout> tag at a desired place where the content needs to appear. (e.g: on the basket page)

Example code how to set up the express checkout web component:

html

Copy

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Basket</title>

  <script
    src="https://${tenant-space}.checkout.api.scayle.cloud/frontend/express/js?appId=${shopId}"
    defer>
  </script>
  
  <script>
    ExpressComponent.addEventListener('consent-missing', ({ detail }) => {
      // detail.provider === "paypal" || "klarna"
      const newConsent = { ...currentConsent, [detail.provider]: true };
      ExpressComponent.setAttribute('consent', JSON.stringify(newConsent));
    });

    ExpressComponent.addEventListener('express-checkout-finished', ({ detail }) => {
      // detail.isFinalized === true || false
      // detail.id === transaction id
       
      if (!detail.isFinalized) {
        // Multi-step checkout -> user needs to review order
        // Mount normal Checkout Webcomponent providing transaction-id attribute
        // Checkout's review page will be shown 
      } else {
        // One-step checkout -> order completed -> show OSP
      }
    });

    ExpressComponent.addEventListener('invalid-access-token', ({ detail }) => {
      // access-token is expired/invalid -> update attribute with a fresh one
      ExpressComponent.setAttribute('access-token', newFreshToken);
    });

    ExpressComponent.addEventListener('payment-closed', ({ detail }) => {
      // user closed the payment widget or cancelled the transaction
    });

    ExpressComponent.addEventListener('express-error', ({ detail }) => {
      // express flow errors
    });
  </script>
  
</head>
<body>
...
<scayle-express-checkout
  jwt="${jwt}"
  access-token="${accessToken}"
  origin="web"
  consent="{"paypal":true,"klarna":false"}"
  basket-total="5400"
></scayle-express-checkout>
...
</body>
</html>

Attributes

Events

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 not set to true , any attempt of your customer to proceed to Express Checkout will trigger the consent-missing event.

It is the responsibility of the storefront to handle the consent-missing event and prompt the user to accept cookies. After cookies are accepted, the web component attribute for consent must be changed by the storefront and it will automatically mount the SDK, allowing the user to proceed.

Review Page

This section details the implementation of the express checkout review page, that is used for multi-step express checkout flows. 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