> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.solvimon.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server. # Quickstart Install the SDK and render your first checkout screen in under 10 minutes. --- ## Install the package ```bash 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](/platform-guides/customers-and-billing/self-serve-plan-changes), 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. ```mermaid sequenceDiagram participant B as Browser participant S as Your backend participant API as Solvimon API B->>S: session start S->>API: POST /v1/portal-urls (secret key) API-->>S: portal object S-->>B: portal object (JSON) B->>B: createComponent({ portalObject }) ``` See the [Create a portal URL](https://docs.solvimon.com/api-docs/transaction-api/portal-urls/post-portal-urls) 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. > **Warning** > > 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. #### Add a mount point Give the SDK a container to render into. Anywhere on the page works; here it's a `
` with a `card` class for styling. **`index.html (lines 1-13)`** ```html index.html (lines 1-13) Solvimon SDK JavaScript Example
``` #### Import the SDK Import `createSolvimonCore` from the core package and grab the container you just added. **`index.html (lines 16-18)`** ```html index.html (lines 16-18) import { createSolvimonCore } from '@solvimon/solvimon-web/core'; const container = document.getElementById('sdk-root'); ``` #### 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](https://docs.solvimon.com/api-docs/transaction-api/portal-urls/post-portal-urls) endpoint, scoped to the customer initiating the checkout. Replace every placeholder value here with a real one. **`index.html (lines 24-32)`** ```html index.html (lines 24-32) // 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', }; ``` #### Configure the SDK instance `createSolvimonCore` sets the environment, locale, logging, and branding shared by every component or screen you mount from it. **`index.html (lines 34-44)`** ```html index.html (lines 34-44) const solvimon = createSolvimonCore({ environment: 'TEST', locale: 'en-US', logLevel: 'info', branding: { colors: { primary: '#1d4ed8', secondary: '#0f172a', }, }, }); ``` #### 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. **`index.html (lines 46-53)`** ```html index.html (lines 46-53) const unmount = solvimon.createScreen('checkout', { container, portalObject: checkoutPortalObject, configuration: { email: 'john@example.com', countryCode: 'NL', }, }); ``` #### Clean up on unload Call `unmount` when the container leaves the page, so the SDK can tear down its listeners and state. **`index.html (lines 55-57)`** ```html index.html (lines 55-57) window.addEventListener('beforeunload', () => { unmount?.(); }); ``` #### Complete files **`index.html`** ```html index.html Solvimon SDK JavaScript Example
```