API Initialization and Execution Order Control

Since: 1.3.3

The hyvaCheckout.api sub-namespace provides methods for controlling the timing and execution order of JavaScript code that interacts with the Hyvä Checkout Frontend API. These methods ensure that custom code runs only after the checkout API is fully initialized, preventing race conditions and undefined reference errors.

after

The hyvaCheckout.api.after method registers a callback to execute once the Hyvä Checkout Frontend API has fully initialized. If the API is already initialized when after is called, the callback executes immediately. This method is essential when registering custom validators, payment handlers, or any code that depends on hyvaCheckout sub-namespaces being available.

Use the checkout:init:after window event when you simply want to execute code independently of any result and with the certainty that everything belonging to the API has run.

Parameters:

• callback (callable, required) - The callback that needs to be executed as soon as the API is initialized.
• options (object, optional)
  • stackPosition (int, optional) - Controls execution order; lower values run first. Default is 500.

Returns:

• Promise<void> - Resolves after the callback has executed.

The following example demonstrates registering a custom validator that waits for the Frontend API to initialize before accessing the hyvaCheckout.validation sub-namespace.

Registering a custom validator with stackPosition control with hyvaCheckout.api.after

Custom Validator Registration Example

<script>
    (() => {
        // Configure execution order: run before validators with higher stackPosition
        // Default stackPosition is 500 if not specified
        const options = {
            stackPosition: 400
        };

        const callback = () => {
            // Register a custom async validator
            // Developers are responsible for handling any validation errors
            hyvaCheckout.validation.register('sensible-validation-name', async () => {
                // Simulate an async API call with a 2-second delay
                await new Promise(resolve => setTimeout(resolve, 2000));

                // Simulate a random validation result (true or false)
                const valid = Math.random() < 0.5;

                // When validation fails, the developer must handle the error
                // Example: display a message using hyvaCheckout.messenger API
                if (valid === false) {
                    console.log('Validation failed – error handling must be implemented manually.');
                }

                // Validators must always return true (valid) or false (invalid)
                return valid;
            });
        };

        // Wait for Frontend API initialization before registering the validator
        hyvaCheckout.api.after(callback, options)
            // Chain additional functionality after successful registration
            .then(() => console.log('Validator registration complete.'));
    })();
</script>

priority

Since: 1.3.4

Reserved for core contributions only; documented here for awareness and understanding of the execution order system.

The hyvaCheckout.api.priority method allows core systems to execute before standard registered callbacks. This method wraps the after method with a fixed stackPosition of 20, ensuring priority callbacks run before those registered via after (which default to stackPosition: 500).

Priority values below 20 are reserved and should not be used in custom implementations.

The following example shows how priority callbacks execute before standard after callbacks.

hyvaCheckout.api.priority callback execution order

Priority Method Usage (Core Only)

<script>
    (() => {
        // IMPORTANT: Reserved for core contributions only
        hyvaCheckout.api.priority(
            () => console.log('Executes before callbacks registered via hyvaCheckout.api.after')
        ).then(() => console.log('Priority callback execution complete.'));
    })();
</script>