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 example below mounts the checkout screen into a #sdk-root container.

The portalObject must come from your backend. It’s a PORTAL_URL resource you create via the Solvimon API for the customer initiating the checkout. Replace the placeholder values with a real one.

Checkout example

1 <!doctype html>
2 <html lang="en">
3     <head>
4         <meta charset="UTF-8" />
5         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6         <title>Solvimon SDK JavaScript Example</title>
7     </head>
8     <body>
9         <main>
10             <section class="card">
11                 <div id="sdk-root"></div>
12             </section>
13         </main>
14 
15         <script type="module">
16             import { createSolvimonCore } from '@solvimon/solvimon-web/core';
17 
18             const container = document.getElementById('sdk-root');
19 
20             if (!container) {
21                 throw new Error('Missing #sdk-root container');
22             }
23 
24             // Replace these placeholder values with a real checkout portal object from your backend.
25             const checkoutPortalObject = {
26                 object_type: 'PORTAL_URL',
27                 id: 'purl_example',
28                 type: 'INIT_PRICING_PLAN_SUBSCRIPTION',
29                 pricing_plan_id: 'ppl_example',
30                 token: 'replace-with-a-real-portal-token',
31                 status: 'PUBLISHED',
32             };
33 
34             const solvimon = createSolvimonCore({
35                 environment: 'TEST',
36                 locale: 'en-US',
37                 logLevel: 'info',
38                 branding: {
39                     colors: {
40                         primary: '#1d4ed8',
41                         secondary: '#0f172a',
42                     },
43                 },
44             });
45 
46             const unmount = solvimon.createScreen('checkout', {
47                 container,
48                 portalObject: checkoutPortalObject,
49                 configuration: {
50                     email: 'john@example.com',
51                     countryCode: 'NL',
52                 },
53             });
54 
55             window.addEventListener('beforeunload', () => {
56                 unmount?.();
57             });
58         </script>
59     </body>
60 </html>

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).

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 example below mounts the checkout screen into a #sdk-root container.

Checkout example

1 <!doctype html>
2 <html lang="en">
3     <head>
4         <meta charset="UTF-8" />
5         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6         <title>Solvimon SDK JavaScript Example</title>
7     </head>
8     <body>
9         <main>
10             <section class="card">
11                 <div id="sdk-root"></div>
12             </section>
13         </main>
14 
15         <script type="module">
16             import { createSolvimonCore } from '@solvimon/solvimon-web/core';
17 
18             const container = document.getElementById('sdk-root');
19 
20             if (!container) {
21                 throw new Error('Missing #sdk-root container');
22             }
23 
24             // Replace these placeholder values with a real checkout portal object from your backend.
25             const checkoutPortalObject = {
26                 object_type: 'PORTAL_URL',
27                 id: 'purl_example',
28                 type: 'INIT_PRICING_PLAN_SUBSCRIPTION',
29                 pricing_plan_id: 'ppl_example',
30                 token: 'replace-with-a-real-portal-token',
31                 status: 'PUBLISHED',
32             };
33 
34             const solvimon = createSolvimonCore({
35                 environment: 'TEST',
36                 locale: 'en-US',
37                 logLevel: 'info',
38                 branding: {
39                     colors: {
40                         primary: '#1d4ed8',
41                         secondary: '#0f172a',
42                     },
43                 },
44             });
45 
46             const unmount = solvimon.createScreen('checkout', {
47                 container,
48                 portalObject: checkoutPortalObject,
49                 configuration: {
50                     email: 'john@example.com',
51                     countryCode: 'NL',
52                 },
53             });
54 
55             window.addEventListener('beforeunload', () => {
56                 unmount?.();
57             });
58         </script>
59     </body>
60 </html>

1	<!doctype html>
2	<html lang="en">
3	<head>
4	<meta charset="UTF-8" />
5	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6	<title>Solvimon SDK JavaScript Example</title>
7	</head>
8	<body>
9	<main>
10	<section class="card">
11	<div id="sdk-root"></div>
12	</section>
13	</main>
14
15	<script type="module">
16	import { createSolvimonCore } from '@solvimon/solvimon-web/core';
17
18	const container = document.getElementById('sdk-root');
19
20	if (!container) {
21	throw new Error('Missing #sdk-root container');
22	}
23
24	// Replace these placeholder values with a real checkout portal object from your backend.
25	const checkoutPortalObject = {
26	object_type: 'PORTAL_URL',
27	id: 'purl_example',
28	type: 'INIT_PRICING_PLAN_SUBSCRIPTION',
29	pricing_plan_id: 'ppl_example',
30	token: 'replace-with-a-real-portal-token',
31	status: 'PUBLISHED',
32	};
33
34	const solvimon = createSolvimonCore({
35	environment: 'TEST',
36	locale: 'en-US',
37	logLevel: 'info',
38	branding: {
39	colors: {
40	primary: '#1d4ed8',
41	secondary: '#0f172a',
42	},
43	},
44	});
45
46	const unmount = solvimon.createScreen('checkout', {
47	container,
48	portalObject: checkoutPortalObject,
49	configuration: {
50	email: 'john@example.com',
51	countryCode: 'NL',
52	},
53	});
54
55	window.addEventListener('beforeunload', () => {
56	unmount?.();
57	});
58	</script>
59	</body>
60	</html>