Hyva Compatibility Add-On

The Hyva add-on renders One Step Checkout without Magento's Luma checkout runtime. It uses Hyva and Alpine for the page, then sends addresses, shipping choices, payment data and agreements through Magento's normal cart services.

• Composer package: mageb2b/onestepcheckout-hyva
• Magento module: MageB2B_OneStepCheckoutHyva
• Required base package: mageb2b/onestepcheckout
• Required storefront: Hyva Default Theme

Install this package only on store views that use Hyva. Luma, Blank and themes based on Magento's standard checkout templates use the base package by itself.

Install the add-on

Install and configure the base One Step Checkout package first:

composer config bearer.repo.softwaresilo.io <token>
composer config repositories.softwaresilo composer https://repo.softwaresilo.io/
composer require mageb2b/onestepcheckout-hyva:*

php bin/magento module:enable MageB2B_OneStepCheckoutHyva
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Run the static-content deployment required by the Magento mode and storefront locales. The add-on has no separate Admin configuration section. It reads the settings from Stores > Configuration > MageB2B > One Step Checkout.

Checkout coverage

The Hyva page supports the base checkout controls and Magento contracts listed below.

Store scope, locale and quote currency come from Magento. The add-on does not hard-code a store code or currency.

Payment methods

The default renderer covers payment methods that do not need extra browser-side fields. Examples include Check / Money Order, Bank Transfer, Cash on Delivery and Zero Subtotal when Magento makes them available for the quote.

Purchase Order is included separately because Magento requires a purchase-order number. Its renderer validates the field and sends po_number through Magento's native payment data.

Payment providers often own more of the checkout flow. A provider-specific adapter is required when a method must:

• tokenize card or bank details in the browser;
• render a hosted widget or payment element;
• open a provider approval window;
• redirect the customer away from Magento;
• resume after 3-D Secure or another challenge.

The adapter registers with the public payment renderer contract, validates its own fields and builds the provider payload. Installing the Hyva add-on does not install or enable Stripe, PayPal or another payment provider.

Address and order submission

The checkout uses Magento's customer and guest cart REST routes. A signed-in customer may select an address-book entry or enter a new address. A guest supplies an email and the required address data. Shipping estimation, shipping-information submission and payment-information submission remain separate Magento operations even though the customer sees one page.

The final order action stays disabled until the visible form is valid. Magento still performs its own server-side validation for addresses, stock, totals, agreements, payment and reCAPTCHA. A successful client-side check does not bypass those rules.

Multi-address behavior

The multi-address link appears only when all of these conditions are true:

1. the customer is signed in;
2. Magento allows checkout with multiple addresses;
3. One Step Checkout's Multi-Address Shipping > Enable setting is on;
4. the cart is eligible for Magento multi-address checkout.

The link enters the base package's multi-address process. Products and quantities can then be assigned to addresses, followed by shipping details, billing and payment, order review and the multi-order confirmation page. See Multi-address shipping.

Optional functions and dependencies

The Hyva page respects both the One Step Checkout setting and the underlying Magento capability. Gift Message, for example, needs the extension setting and Magento's order-level gift-message setting. Google Places needs a valid browser API key and allowed storefront origin. GA4 needs the store's analytics and consent implementation.

Cart recovery remains a base-package process. A recovery link restores or merges the quote according to configuration, then sends the buyer to the checkout route used by the active store view.

Verify the checkout

Run complete orders with fictional data rather than checking only that the page opens:

1. place a guest order with a fieldless offline payment method;
2. place a signed-in order using a saved address;
3. add a new customer address and confirm whether it is saved as selected;
4. test a virtual cart without shipping fields;
5. apply and remove a coupon;
6. submit every enabled checkout extra and inspect the Admin order;
7. test Purchase Order with an empty and valid purchase-order number;
8. test multi-address shipping when it is enabled;
9. repeat the main flow on a mobile viewport;
10. inspect the final network request for a successful Magento response and any required reCAPTCHA header.

Repeat provider-specific payments with the provider's sandbox credentials. A successful offline payment does not prove that a tokenized or redirected payment integration works.

Troubleshooting

The checkout page is blank or still uses Luma

Confirm the active theme and module status. Both the base and Hyva modules must be enabled. Clear layout, block and full-page caches after deployment and confirm that the Hyva layout handles are active for the store view.

No shipping methods are available

Check the entered country, region, postal code and cart contents. The add-on displays the methods Magento returns; it does not create shipping rates. Inspect the estimate request and response before changing checkout templates.

The selected payment method has no fields

Check whether the method is fieldless or needs an adapter. Purchase Order has a bundled field. Other methods with browser-side collection, tokenization or redirects need their own compatible renderer.

Place Order returns a validation error

Read the response from Magento's payment-information endpoint. Check required address fields, active agreements, payment data and reCAPTCHA. The cart remains active after a rejected request so the customer can correct the problem.

A customization has no place in the layout

Use the checkout's neutral layout slots and renderer registration points. Do not add project-specific fields to the Hyva bridge itself. The module that owns the data should provide its own block, script and persistence contract.

Related guides

• Configuration
• Checkout layout
• Shipping and payment
• Checkout extras
• Multi-address shipping
• Common Issues