Frontend Components

Quickstart

Install the SDK and render your first checkout screen in under 10 minutes.

Install the package

npm install @solvimon/solvimon-web

The portal object

Every Solvimon component and screen mounts with a portal object: the bridge between your backend (which holds your secret API key) and the SDK (which runs in the customer’s browser).

It’s a PORTAL_URL resource you create via the Solvimon API. It scopes a single SDK session to one customer, one checkout, or one upgrade flow, and carries a short-lived token the SDK exchanges for an access token at runtime.

Where it comes from

Always your backend. Creating a PORTAL_URL requires your secret API key, which must never reach the browser.

See the Create a portal URL endpoint for the full request and response shape, including the available type values.

Lifetime

Portal objects are short-lived: mint a fresh one each time a customer starts a session. Don’t cache them across sessions or share them between customers.

The token inside the portal object is safe to send to the browser; it’s scoped to a single resource and expires. Your secret API key is not, and must stay on your backend.

Render the checkout screen

The walkthrough below mounts the checkout screen into a #sdk-root container, one piece at a time.

  1. Add a mount point

    Give the SDK a container to render into. Anywhere on the page works; here it’s a <section> with a card class for styling.

  2. Import the SDK

    Import createSolvimonCore from the core package and grab the container you just added.

  3. Supply the portal object

    The portalObject must come from your backend. It’s a PORTAL_URL resource you create via the Create a portal URL endpoint, scoped to the customer initiating the checkout. Replace every placeholder value here with a real one.

  4. Configure the SDK instance

    createSolvimonCore sets the environment, locale, logging, and branding shared by every component or screen you mount from it.

  5. Mount the checkout screen

    createScreen mounts the screen and returns an unmount function. Pass the portal object and any per-screen configuration, such as a prefilled email or country code.

  6. Clean up on unload

    Call unmount when the container leaves the page, so the SDK can tear down its listeners and state.

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Solvimon SDK JavaScript Example</title>
    </head>
    <body>
        <main>
            <section class="card">
                <div id="sdk-root"></div>
            </section>
        </main>
        <script type="module">
            import { createSolvimonCore } from '@solvimon/solvimon-web/core';
            const container = document.getElementById('sdk-root');
            if (!container) {
                throw new Error('Missing #sdk-root container');
            }
            // Replace these placeholder values with a real checkout portal object from your backend.
            const checkoutPortalObject = {
                object_type: 'PORTAL_URL',
                id: 'purl_example',
                type: 'INIT_PRICING_PLAN_SUBSCRIPTION',
                pricing_plan_id: 'ppl_example',
                token: 'replace-with-a-real-portal-token',
                status: 'PUBLISHED',
            };
            const solvimon = createSolvimonCore({
                environment: 'TEST',
                locale: 'en-US',
                logLevel: 'info',
                branding: {
                    colors: {
                        primary: '#1d4ed8',
                        secondary: '#0f172a',
                    },
                },
            });
            const unmount = solvimon.createScreen('checkout', {
                container,
                portalObject: checkoutPortalObject,
                configuration: {
                    email: 'john@example.com',
                    countryCode: 'NL',
                },
            });
            window.addEventListener('beforeunload', () => {
                unmount?.();
            });
        </script>
    </body>
</html>