scriptology / mfe-checkout

Commerce Layer Hosted Checkout

Commerce Layer React Checkout

The Commerce Layer Checkout application (React) provides you with a PCI-compliant, PSD2-compliant, and production-ready checkout flow powered by Commerce Layer APIs. You can fork this repository and deploy it to any hosting service or use it as a reference application to build your own.

What is Commerce Layer?

Commerce Layer is a multi-market commerce API and order management system that lets you add global shopping capabilities to any website, mobile app, chatbot, wearable, voice, or IoT device, with ease. Compose your stack with the best-of-breed tools you already mastered and love. Make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.

Table of contents

• Getting started
• Hosted version
• Features
• Contributors guide
• Help and support
• License

---

Getting started

1. Create your organization and get your credentials by following one of our onboarding tutorials.

2. Set the environment variable NEXT_PUBLIC_SLUG on your hosting provider to your organization slug (subdomain) and be sure to build the forked repository using the node environment (NODE_ENV) as production.

3. Deploy the forked repository to your preferred hosting service. You can deploy with one click below:

4. Build your sales channel with your favorite technologies and frameworks by leveraging our developer resources and documentation.

5. Get an access token for your application. You should generate this in your sales channel or use our JavaScript authentication library.

6. Create an order associated with some line items.

7. Checkout the previously created order using the URL format: <your-deployed-checkout-url>/:order_id?accessToken=<your-access-token>

Example

https://checkout.yourbrand.com/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9

Hosted version

Any Commerce Layer account comes with a hosted version of the Checkout application that is automatically enabled. You can customize it by adding your organization logo, favicon, primary color, Google Tag Manager ID, support telephone, and email address.

You can use the hosted version of the Checkout application with the following URL format: https://<your-organization-subdomain>.commercelayer.app/checkout/:order_id?accessToken=<your-access-token>

Example

https://yourbrand.commercelayer.app/checkout/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9

CLI plugin

If you are using Commerce Layer CLI, you can leverage the checkout plugin to generate the URL from an SKU code (using the -S flag), a bundle code (using the -B flag), or an order ID (using the -O flag):

commercelayer checkout -S <skuCode>:<quantity> --open
commercelayer checkout -B <bundleCode>:<quantity> --open
commercelayer checkout -O <orderID> --open

Features

The Commerce Layer Checkout application supports most of the main features available through the Commerce Layer API. We're working to add a few missing ones within the next development iterations.

The Checkout application includes an order summary and a checkout flow made of 3 steps:

1. Customer
2. Delivery
3. Payment

Each step can be edited by the customer at any time. The order status determines the current step, which stays consistent across sessions.

Once the checkout is successfully completed, the customer is redirected to a thank you page.

Order summary

The Checkout application shows a visual summary of the order that's about to be placed detailing all the involved line items (frequency of recurring items, order amounts, shipping costs, taxes, discounts, etc.).

We suggest properly setting up all the SKU information (in terms of names and images) on the Commerce Layer admin dashboard or via API so that this part is fully populated.

SKU options

The Checkout application supports SKU options. If a line item is associated with one or more line item options the details are visible in the order summary. Line item option prices aren't displayed but they are included in the line item amount.

Gift cards and coupons

The Checkout application supports gift cards and coupon codes (just fill in the related field in the order summary). You can use a gift card or coupon to pay — in total or in part — for the order. A single gift card and a coupon code can also be used together to pay for the same order.

Bundles

The Checkout application supports bundles and shows them as a single item both in the order summary and within the Delivery step. The SKUs belonging to bundles may still be split across more than one shipment, based on their availability and the selected inventory model strategy.

Return to cart

If the order has the attribute cart_url set, a "Return to cart" link will be displayed.

Order refresh

When the checkout is opening, after getting the organization settings, the order might be refreshed if some conditions are met. Check the flowchart below to better understand how this logic works:

flowchart LR
    A[Start] --> B{order.autorefresh?}
    B -- true --> C{Token type?}
    C -- Sales channel --> G
    C -- Customer token --> D{order.guest?}
    D -- false --> G[No refresh]
    D -- true --> F
    B -- false ----> F[Refresh sync]

Customer step

Here is where customers provide their email address, billing and shipping information.

Logged customers

If the access token used to build the checkout URL is a customer token customers can select one of their saved addresses from their address book and use it as the billing and/or shipping address. If the customer has only one address in the address book the Checkout application will use this address as the billing and shipping address and skip the Customer step.

Digital products

In the case of digital product purchases (i.e. SKUs with the do_not_ship flag enabled), the shipping address form doesn't appear.

Locking the shipping country code

If the order has the attribute shipping_country_code_lock set, customers can select only the specified country code in the shipping address form. If they select a different country for the billing address, the shipping address section will open automatically with the country code already selected and disabled.

Delivery step

Here is where customers select a shipping method for each shipment of their order. External shipping cost are partially supported by the Checkout application at the moment.

Single shipping method

If there is only one available shipping method per shipment, the Checkout application will autoselect that shipping method for each shipment of the order and skip the Delivery step.

Shipping zone check

If the shipping address is outside the associated shipping zone customers will receive an error and won't be able to place the order.

Out-of-stock items

If one of the items in the order is out of stock customers will get an error message and won't be able to place the order. If the order has the attribute cart_url set, the error message will contain a link to let them go back and edit the shopping cart.

Digital products

In the case of digital product purchases (i.e. SKUs with the do_not_ship flag enabled), this step doesn't appear.

Payment step

Here is where customers select a payment method and place the order.

We're working to make all the payment gateways supported by Commerce Layer available out-of-the-box in the Checkout application. External payments are not supported by the Checkout application at the moment. For all the other gateways information please refer to the table below.

Payment gateway	Supported payment methods	Customer wallet
Adyen	Credit card / PayPal / Klarna	✓
Braintree	Credit card	✓
Klarna	Klarna	✗
PayPal	PayPal	✗
Stripe	Credit card / Apple Pay / Google Pay / PayPal / Klarna	✓
Manual gateway	Manual payment	✗

To automatically accept payment methods enabled in the Stripe dashboard please make sure to properly set up the auto_payments option on your Stripe gateway.

When using PayPal via Adyen please make sure to properly set up third-party access on your PayPal first.

Only v68 of Adyen Payment API is supported by the Checkout application. Make sure that your Adyen payment gateway is configured properly on Commerce Layer.

Logged customers

If the access token used to build the checkout URL is a customer token customers will see their saved credit cards in their customer wallet and will be able to reuse them to accelerate the payment process.

Single payment method

If there is only one payment method available in the market the order belongs to, the Checkout application will autoselect that payment method and let you directly add your payment details to the order.

Zero-balance

In case the order balance is zero — e.g. the customer is paying with a gift card or coupon code for the full amount of the order — this step doesn't appear.

Privacy acceptance

If the privacy_url and terms_url attributes of the order are set an info paragraph will be displayed before the "Place order" button, including the related links and a checkbox to accept the terms. Customers won't be able to place the order unless they check it and agree.

Thank you page

The page is displayed on successful order placement and features a recap of the order in terms of SKUs, bundles, billing/shipping addresses, and payment information. It is possible to show some support references (phone and email) by setting the support_phone and support_email attributes of the order. If the order's return_url attribute is set a link to continue shopping will be displayed on the page as well.

Supported languages

The Checkout application language is set by the language_code attribute of the order. At the moment, languages supported out of the box are:

• English
• Italian
• German

The fallback language is English.

If you want to contribute and translate the Checkout application into a language that's not currently available feel free to create a PR.

Google Tag Manager integration

If gtm_id attribute is set on the organization settings it will be used to send Enhanced Ecommerce events. The Checkout application currently tracks the following events:

• begin_checkout
• add_shipping_info
• add_payment_info
• purchase

If the Delivery step is automatically populated, the add_shipping_info event will be fired as soon as the Checkout application sets the related shipping method. If the customer opens the Delivery step from the UI and clicks on the "Continue to payment" button, the event will be fired once more.

Contributors guide

1. Fork this repository (you can learn how to do this here).

2. Clone the forked repository like so:

git clone https://github.com/<your username>/mfe-checkout.git && cd mfe-checkout

3. First, install dependencies and run the development server:

pnpm install
pnpm dev

4. Set your environment with .env.local starting from .env.local.sample.

5. Open http://localhost:3000 with your browser to see the result. You can use the following format to open the checkout: http://localhost:3000/:orderId?accessToken=<your-access-token>.

6. Make your changes and create a pull request (learn how to do this).

7. Someone will attend to your pull request and provide some feedback.

Need help?

1. Join Commerce Layer's Slack community.

2. Create an issue in this repository.

3. Ping us on Twitter.

License

This repository is published under the MIT license.