Skip to content

Frontend API Backport Module

The Frontend API Backport module (hyva-themes/magento2-hyva-checkout-frontend-api) brings the latest payment integration features and security improvements to older Hyvä Checkout versions. This allows PSPs and agencies to build integrations using current API capabilities while supporting merchants who haven't yet upgraded their checkout.

Why Use the Backport Module?

The backport module solves a common challenge: payment integrators need access to the latest Frontend API features, but merchants may be running older checkout versions. Rather than forcing upgrades or maintaining multiple integration versions, the backport provides:

  • Latest payment API features on older checkout installations
  • Security improvements without full checkout upgrades
  • Forward compatibility for integrations built with current API patterns
  • Reduced maintenance burden for PSPs and agencies supporting multiple merchants

Hyvä maintains backwards compatibility wherever possible, so upgrading the backport module is safe and recommended whenever a new version is released.

When to Use the Backport

Use the backport module when:

  • You're building a payment integration that requires Frontend API features not present in the merchant's checkout version
  • You need security fixes from newer checkout versions without a full upgrade
  • You have multiple modules requiring different Frontend API versions (use the latest backport to satisfy all requirements)

Version releases

A new backport version is released whenever the main Hyvä Checkout package includes changes to backport-related files. Releases may not occur on the same day as the main checkout release.

Installation

Any customer with a Hyvä Checkout license can install the backport module. Follow these steps to add it to your project:

Step 1: Configure the Hyvä packagist.com repository (if not already configured):

This step usually is already completed during installation of Hyvä Checkout.

Configure Composer authentication
# Add your license authentication key to auth.json
# Replace yourLicenseAuthenticationKey with your actual key
composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthenticationKey

# Add the private packagist repository
# Replace yourProjectName with your project name
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/

Step 2: Require the backport package:

Install the backport module
composer require 'hyva-themes/magento2-hyva-checkout-frontend-api'

Future Development

The backport module initially focused on payment and security improvements. Expansion to include additional JavaScript-specific upgrades is under consideration, though no specific roadmap exists at this time.

Module Structure

Understanding the backport module's internal organization helps when troubleshooting or reviewing customizations. The module maintains a clear structure to ensure compatibility while minimizing conflicts.

Template Overrides (view/)

The module overrides only templates directly related to the Frontend API, particularly payment-related templates. These templates are referenced via layout XML and given new template paths.

PHP Preferences (Preference/)

Contains DI preferences for PHP classes that exist in supported checkout versions but require additional methods from newer versions. Preferences restore compatibility by adding missing method implementations.

Origin Classes (Origin/)

Contains classes that are completely missing from older checkout versions. The folder structure mirrors the main Hyvä Checkout package structure for easy maintenance.

Deprecated on purpose

Origin classes are marked as deprecated to signal that they're temporary backports. Once the merchant upgrades their checkout, these classes become redundant.

Forward-Compatibility Classes

Additional classes scattered throughout the module provide forward-compatibility for features like frontend configuration during page loads and Magewire subsequent requests.

Frequently Asked Questions

Can the backport be installed alongside the latest checkout version?

Yes, the backport module can be installed even when running the latest Hyvä Checkout version. However, the backport takes priority over core files. If you've made customizations to any files that the backport overrides, you'll need to review and adjust them.

In practice, this is rarely an issue since most overwritten files are marked as @internal and should not be customized.

When do I need the backport module?

Install the backport when you need Frontend API features that don't exist in the merchant's checkout version. The module focuses on features commonly required by PSP and shipping integrators, with an emphasis on payment-related functionality.

If multiple modules in your project require the backport, always use the latest version. Vendors requiring the backport should use a flexible version constraint (such as *) or implement a strategy that ensures the latest version is installed.

What happens when the merchant upgrades their checkout?

Once the merchant upgrades to a checkout version that includes the backported features natively, the backport module becomes redundant. It can remain installed without causing issues, but it's no longer providing additional functionality. Consider removing it to reduce complexity.