Skip to content

Quickstart

A checkout system can quickly evolve into a complex ecosystem where everything converges. Our challenge was to offer a platform flexible enough to meet all the typical expectations of a checkout system while also accommodating as many requirements and desires as possible. The key challenge is finding the sweet spot between complexity and simplicity to create developer happiness while allowing for the construction of any desired checkout.

Prior knowledge

Working with Hyvä Checkout assumes familiarity with the following aspects of Magento development:

  • Layout XML and *.phtml template files
  • Block classes
  • PHP ViewModels
  • Magewire

Key Awareness Points

  1. Hyvä Checkout is essentially an empty shell filled with components that operate independently of each other. This design choice prioritizes flexibility, allowing components to be displayed at any desired step as long as they operate independently.

  2. Payment methods may not always appear on the same step as the "Place Order" button, unlike in the Luma checkout, for example. It is considered bad practice to assume it will. Therefore, we always recommend testing your payment method on a step that precedes another step.

  3. You can make the checkout as complex as you want. Depending on the task, our APIs serve as extensions of your toolkit and primarily help simplify the necessary complexity. Understanding key concepts such as Magewire and the Evaluation API is therefore important.

  4. Certain concepts can appear in various contexts. For example, consider the Evaluation API, originally intended for Magewire driven components, but also extended to the Place Order Service API because of its power and flexibility.

  5. Many of the new concepts we have introduced may initially seem complex, but they are fundamentally based on foundational knowledge you already have when working with Magento and/or Magewire. From the inception of building this new checkout, our goal has been to stay as close as possible to these fundamentals.

Fundamental Pillars

Building a checkout isn't easy, especially a flexible one like Hyvä Checkout. Many areas need to be taken into consideration to make everything work together. Therefore, Hyvä Checkout is built upon several fundamental pillars that you should be aware of. Everything else is additional and, when used, is typically put in place due to edge cases or specific requirements. Overall, knowing about these fundamentals and understanding them is the best starting point for getting into Hyvä Checkout.

About to write a ton of custom code to make something work? We've probably already got you covered, you just aren't aware of the options yet. So please ask us in Slack, we're here for guidance!

Magewire

Current version: V1-latest

The core engine behind Hyvä Checkout. It takes care of areas such as step navigation, Evaluation API, state management and rendering. The Main Magewire component is therefore a crucial one to examine, but should never be overwritten or modified.

Checkout components can be built with any technology stack you prefer. Our hyvaCheckout frontend API will get you quite far, but please keep in mind it will require more custom work since the core reacts primarily to Magewire-driven components.

Layout XML

We've built a very flexible layout where much of the guidance has already been done for you. This means components are stored within the hyva_checkout_components.xml referencing the hyva.checkout.components block, whilst <script> blocks can be either stored directly in the hyva.checkout.api-v1.after container or as a child of one of the sub-containers, which are all based on the sections of our hyvaCheckout. JS namespace. Looking over all the available containers is key to knowing where to store your custom code. For every single situation, there is a container defined, ensuring things are loaded in the right order.

Checkout Config

The hyva_checkout.xml config sitting within the /etc folder is a key subject to understand in order to build custom checkouts. Going over all options is very useful to avoid situations where you have to write a lot of custom code to make things work.

Evaluation API

This PHP-driven API is based on the Magewire mindset, letting results travel from the server to the frontend where those results are processed.

The Evaluation API has been built to let you check all data on the backend, which is normally the source of truth, and send along a versatile list of instructions to the frontend which will take care of those instructions either directly or based on a click of the navigation button like "Go to next step" or "Place the order".

Understanding the principle of the Evaluation API is crucial since it's being used within the core all over the place.

Please refer to our dedicated page about the Evaluation API.

Place Order Services

Especially for PSPs, this is a crucial area to be aware of. By default, the default Place Order Service will handle all orders. However, based on the payment method selected, the system will search for a corresponding place order service bound by its name and, when existing, will use that service to handle the order placement which should be abstracted from our abstraction layer.

Since version 1.3.6, we also provide a JS-driven option for Place Order Services. More details can be found here.

Frontend API

Out of the box, we initialize our hyvaCheckout frontend API. This API provides developers with a large variety of tools to avoid you having to reinvent the wheel over and over and to keep things uniform where possible.

The frontend API is divided into subsections such as messaging, order, payment, storage, config etc.

Understanding this API is key to building a robust integration or feature.

Please refer to our dedicated page about the Frontend API.

Files & Folders

We see this happening frequently, where people are unsure about where to store their files and folders. With Hyvä Checkout, this has been made as clear as possible, with almost every aspect having a dedicated location that's designed to be altered when needed without introducing backwards-incompatible changes.

Here's an overview of the most common situations developers will face:

Make a new Magewire component

All checkout components go in the Magewire/Checkout/... directory, perhaps nested in subfolders when needed. Then, to register a component, you use the hyva_checkout_components.xml handle to make them reusable on any step.

Finally, using either a checkout global handle that serves every step, or a specific step handle allows you to move components into the correct columns based on what layout is set for the checkout. Use <move element="" destination=""/> to do so.

A global layout handle can be hyva_checkout_{checkout_name}.xml and a step-specific one can be hyva_checkout_{checkout_name}_{step_name}.xml.

Working with JS-templates

When you decide to work with JavaScript for a specific feature, we've got you covered. Dedicated containers are made available to register situation-specific minimalistic PHTML templates having a <script></script> tag with your custom JavaScript in between.

These scripts are injected outside the dynamic Main component to always be available when the page is loaded. This is required for CSP, for example. Every JavaScript piece needs to be registered using the hyva_checkout_index_index.xml handle alongside the correct container or block reference to inject your block into.

Here's a small list of the most common situations:

Please make sure that you prefix your template directories with view/frontend/hyva/checkout/page/js/v1/. These are left out to avoid table alignment inconsistencies.

API Area Relation Reference Container Template Directory
Storage hyva.checkout.init-storage.after /storage
Config hyva.checkout.init-config.after /config
Validation hyva.checkout.init-validation.after /validation
Evaluation hyva.checkout.init-evaluation.after /evaluation
Evaluation - Executables hyva.checkout.evaluation.executables /evaluation/executables
Navigation hyva.checkout.init-navigation.after /navigation
Payment hyva.checkout.init-payment.after /payment
Shipping hyva.checkout.init-shipping.after /shipping
Message hyva.checkout.init-message.after /message
Loader hyva.checkout.init-loader.after /loader
Viewport hyva.checkout.init-viewport.after /viewport
Debug hyva.checkout.init-debug.after /debug

Not sure where to put your JS-template files?

When you aren't sure about where to put your template file, either the layout location or the directory, you can always fall back to storing them in view/frontend/hyva/checkout/page/js/api/v1 and use the reference container hyva.checkout.api-v1.after. This is also a good place to put your AlpineJS component JS-templates into.

We do always recommend finding a more suitable place that makes more sense, but for uncommon situations this is fine.