Browser Session Storage API for Hyvä Checkout

Since: 1.1.13

The hyvaCheckout.storage sub-namespace provides methods for storing and retrieving key-value pairs in the browser's session storage. This API is essential for persisting payment and shipping data that needs to travel to the server-side Place Order Service when the order is placed.

Built-in Storage Groups

Hyvä Checkout uses two predefined storage groups that automatically transfer data to the backend Place Order Service PHP object:

• payment - Stores payment-related data (tokens, method-specific values, transaction IDs)
• shipping - Stores shipping-related data (carrier preferences, delivery instructions)

You can also define custom groups for your own module's data persistence needs.

setValue

Stores a value in session storage under a specified key, optionally within a named group. Values stored in the payment or shipping groups are automatically available in the Place Order Service on the backend.

Parameters:

• key (string, required) - The storage key identifier
• value (mixed, required) - The value to store (strings, numbers, objects, arrays)
• group (string, optional) - Group name for organizing related values

Returns:

• Promise (since v1.3.4) - Resolves with the stored value after successful storage
• void (before v1.3.4) - No return value in earlier versions

The following example demonstrates storing a payment PIN code that will be available to the Place Order Service on the backend.

Storing a payment value with group assignment

Setting Storage Values with Groups

<script>
    (() => {
        const group = 'payment';
        const key = 'pin';
        const value = 123;

        // Wrap in hyvaCheckout.api.after when setting values on page load
        // This ensures the API is initialized before accessing storage
        // Not required for values set from user interactions (API already initialized)
        hyvaCheckout.api.after(() => {
            // Since v1.3.4: setValue returns a Promise
            hyvaCheckout.storage.setValue(key, value, group)
                .then(storedValue => {
                    if (storedValue === value) {
                        console.log('Value successfully stored in session storage.');
                    }
                });

            // Before v1.3.4: Use getValue to verify storage
            if (hyvaCheckout.storage.getValue(key, group) === value) {
                console.log('Value successfully stored in session storage.');
            }

            // Alternative: Check via getGroupData
            const groupData = hyvaCheckout.storage.getGroupData(group);
            if (groupData && groupData[key] === value) {
                console.log('Value found in group data.');
            }
        });
    })();
</script>

getValue

Retrieves a single value from session storage by key and optional group.

Parameters:

• key (string, required) - The storage key identifier
• group (string, optional) - Group name to search within

Returns:

• mixed - The stored value if found
• undefined - If the key does not exist

Retrieving a stored value

Getting a Single Storage Value

<script>
    (() => {
        hyvaCheckout.api.after(() => {
            // Retrieve value from the payment group
            const pin = hyvaCheckout.storage.getValue('pin', 'payment');

            if (pin !== undefined) {
                console.log('Retrieved PIN:', pin);
            }
        });
    })();
</script>

getGroupData

Retrieves all key-value pairs within a specified storage group as an object.

Parameters:

• group (string, required) - The group name to retrieve

Returns:

• object - All key-value pairs in the group
• null - If the group does not exist or is empty

Retrieving all values in a group

Getting All Group Data

<script>
    (() => {
        hyvaCheckout.api.after(() => {
            // Get all payment-related stored values
            const paymentData = hyvaCheckout.storage.getGroupData('payment');

            if (paymentData) {
                console.log('Payment storage contents:', paymentData);
                // Example output: { pin: 123, token: 'abc123', method: 'credit_card' }
            }
        });
    })();
</script>

removeValue

Removes a single value from session storage by key and optional group.

Parameters:

• key (string, required) - The storage key identifier to remove
• group (string, optional) - Group name containing the key

Returns:

• void - No return value

Removing a stored value

Removing a Single Storage Value

<script>
    (() => {
        hyvaCheckout.api.after(() => {
            // Remove the PIN from payment storage
            hyvaCheckout.storage.removeValue('pin', 'payment');

            // Verify removal
            const pin = hyvaCheckout.storage.getValue('pin', 'payment');
            console.log('PIN after removal:', pin); // undefined
        });
    })();
</script>

clearGroup

Removes all values within a specified storage group.

Parameters:

• group (string, required) - The group name to clear

Returns:

• void - No return value

Clearing an entire storage group

Clearing All Values in a Group

<script>
    (() => {
        hyvaCheckout.api.after(() => {
            // Clear all payment-related stored values
            hyvaCheckout.storage.clearGroup('payment');

            // Verify group is cleared
            const paymentData = hyvaCheckout.storage.getGroupData('payment');
            console.log('Payment group after clear:', paymentData); // null
        });
    })();
</script>

Accessing Storage Data in Place Order Service

Values stored in the payment and shipping groups are automatically passed to the server-side Place Order Service. Access these values in your PHP implementation using the appropriate service methods.