Hyvä Checkout Frontend API Overview

The Hyvä Checkout Frontend API (window.hyvaCheckout) is a JavaScript namespace providing client-side functionality for checkout interactions. The API complements the server-side Magewire components, handling tasks that require browser-level execution such as validation orchestration, navigation control, session storage, and order placement coordination.

API Sub-namespaces

The Frontend API organizes functionality into sub-namespaces, each handling a specific domain of checkout operations.

Sub-namespace	Purpose	Documentation
hyvaCheckout.api	Controls initialization timing and callback execution order	API Initialization
hyvaCheckout.evaluation	Processes backend evaluation results and registers frontend validators	Frontend Evaluation
hyvaCheckout.payment	Registers and manages JavaScript-driven payment methods	Payment Methods
hyvaCheckout.storage	Stores key-value pairs in browser session storage for Place Order Service	Storage API
hyvaCheckout.validation	Manages the validation stack executed before navigation or order placement	Form Validations
hyvaCheckout.navigation	Controls checkout step navigation and history management	-
hyvaCheckout.messenger	Displays messages, dialogs, and notifications to customers	-
hyvaCheckout.main	Orchestrates API initialization and checkout lifecycle	-
hyvaCheckout.config	Provides access to backend configuration passed during initialization	-

For details on the file structure, Layout XML organization, and extension patterns, see the Architecture documentation.

When to Use the Frontend API

The Frontend API serves as a toolkit for browser-level operations that cannot be handled by server-side Magewire components alone. Use the Frontend API when you need to:

• Register custom validators that execute JavaScript logic before step navigation or order placement
• Implement JavaScript-driven payment methods that interact with PSP SDKs or handle client-side payment flows
• Store data in browser session storage that needs to travel to the Place Order Service on the backend
• Execute code after specific sub-namespaces initialize using the event-driven initialization system
• Coordinate frontend actions with backend evaluation results through the Evaluation API integration

How Frontend and Backend Work Together

Hyvä Checkout uses a "backend-first" architecture where Magewire components handle most logic server-side, with the Frontend API providing targeted client-side support. The Evaluation API exemplifies this pattern.

Evaluation API Integration Example

The Evaluation API demonstrates how backend PHP code drives frontend JavaScript behavior. A Magewire component implementing EvaluationInterface returns "evaluation results" that instruct the frontend to perform specific actions.

Step 1: Backend defines validation requirements

The Magewire component specifies what validation should occur and what happens on failure, using PHP to construct the instructions.

Magewire Component with Evaluation Result

<?php
// A Magewire component implementing EvaluationInterface

class ExampleComponent extends \Magewirephp\Magewire\Component
    implements \Hyva\Checkout\Model\Magewire\Component\EvaluationInterface
{
    public function evaluateCompletion(
        \Hyva\Checkout\Model\Magewire\Component\EvaluationResultFactory $resultFactory
    ): \Hyva\Checkout\Model\Magewire\Component\Evaluation\EvaluationResult
    {
        // Create a validation result that triggers the frontend validator 'validateExampleComponent'
        return $resultFactory->createValidation('validateExampleComponent')
            // Define what happens when the frontend validator returns false
            ->withFailureResult(
                $resultFactory->createErrorMessageEvent()
                    ->withCustomEvent('payment:method:error')
                    ->withMessage('Value should be 1234')
                    ->withVisibilityDuration(5000)
             );
    }
}

For complete documentation on evaluation result types and backend implementation, see the Evaluation API documentation.

Step 2: Backend sends instructions to frontend

During page rendering or Ajax updates, the evaluation result is serialized and sent to the browser. The Frontend API receives this data structure containing the validation name, failure handling instructions, and execution parameters.

Evaluation result JSON payload

{
    "example-component-name": {
        "arguments": {
            "name": "validateExampleComponent",
            "detail": {
                "component": { "id": "example-component-name" }
            },
            "stack": { "position": 500 },
            "results": {
                "failure": {
                    "arguments": {
                        "event": "payment:method:error",
                        "detail": {
                            "component": { "id": "example-component-name" },
                            "message": {
                                "text": "Value should be 1234",
                                "type": "error",
                                "duration": 5000
                            }
                        }
                    },
                    "dispatch": true,
                    "result": false,
                    "type": "event"
                }
            }
        },
        "type": "validation"
    }
}

Step 3: Frontend processes instructions and registers validator

The hyvaCheckout.evaluation namespace processes incoming results. For validation-type results, the Frontend API looks for a registered validator callback matching the specified name and adds it to the validation stack.

Frontend Validator Registration

<!-- File: My_Example::page/js/hyva-checkout/api/v1/evaluation/validate-example-component.phtml -->

<script>
    // Wait for the evaluation sub-namespace to initialize
    window.addEventListener('checkout:init:evaluation', () => {
        // Register the validator callback that matches the backend's createValidation() name
        hyvaCheckout.evaluation.registerValidator('validateExampleComponent', (element, component) => {
            const field = element.querySelector('#secret');

            if (field) {
                // Async validation simulating an API call
                return new Promise((resolve, reject) => setTimeout(() => {
                    field.value === '1234' ? resolve(true) : reject();
                }, 2500));
            }

            return false;
        });
    });
</script>

Step 4: Validation executes on navigation or order placement

When the customer clicks "Continue" or "Place Order," all registered validators execute automatically. If a validator returns false or rejects, navigation halts and the backend-defined failure result (error message) displays to the customer.

For more details on form validation patterns, see the Form Validations documentation.