Comfino Web Frontend SDK — integration guide

Everything a developer needs to embed Comfino payments (the checkout paywall and the product-page installment widget / calculator) into any web storefront: a step-by-step guide, copy-paste snippets, runnable examples, and TypeScript type definitions.

This repository is documentation only — no build step, nothing to compile. The SDK itself ships as a minified ES module from the Comfino CDN; you load it straight from a <script> tag or a dynamic import(). This guide is aimed at integrators building a new / custom e-commerce platform integration (the ready-made PrestaShop, WooCommerce and Magento plugins already bundle everything below).

Money is always in the smallest currency unit (grosze for PLN) on the SDK/wire boundary — 199900 means 1 999,00 PLN. The one exception is the DOM-facing resolvePrice() / comfino:price-changed hooks, which use major units (PLN) — each is called out explicitly below.

---

The two integration levels

There are two ways to consume the SDK. Pick per surface — most custom integrations use the bridge for the widget and the SDK API for the paywall.

Level	What it is	Use when
A. Config bridge (zero JS)	Drop a <script src> for a bridge bundle + a <script type="application/json"> config block. The bridge loads the SDK and mounts the control for you.	You render server-side and want a drop-in with no custom JavaScript.
B. SDK API (import())	Dynamically import() the ESM SDK and call its typed methods yourself.	You need full control: custom price logic, custom checkout state handling, SPA lifecycles, a custom payment-method renderer.

Both consume the same ESM bundle; the bridge is a thin wrapper around the SDK API.

---

CDN URLs

Resource	Sandbox (testing)	Production
SDK (ESM)	https://sdk.craty.pl/sdk/v1/comfino-sdk.min.js	https://sdk.comfino.pl/sdk/v1/comfino-sdk.min.js
Paywall bridge (generic)	https://sdk.craty.pl/checkout/v1/comfino-paywall.min.js	https://sdk.comfino.pl/checkout/v1/comfino-paywall.min.js
Widget bridge (generic)	https://sdk.craty.pl/product/v1/comfino-widget.min.js	https://sdk.comfino.pl/product/v1/comfino-widget.min.js
Comfino REST API (v3)	https://api-ecommerce.craty.pl	https://api-ecommerce.comfino.pl

The iframe UI apps (/paywall/v1/…, /widget/v1/…) and CSS (/css/…) / images (/images/comfino/…) are loaded by the SDK itself — you never reference them directly.

CSP: loading a cross-origin ES module requires the SDK host in your script-src (host-source) or 'strict-dynamic' on a nonce policy. See docs/troubleshooting.md.

---

Quick start

Paywall — Level A (config bridge)

<!-- Where the paywall renders in your payment-methods list -->
<div id="comfino-paywall-container"></div>

<!-- Server-rendered config. authToken + loanAmount come from YOUR backend (see below). -->
<script type="application/json" id="comfino-paywall-config">
    {
        "sdkScriptUrl": "https://sdk.craty.pl/sdk/v1/comfino-sdk.min.js",
        "environment": "sandbox",
        "authToken": "<AUTH_TOKEN_FROM_YOUR_BACKEND>",
        "loanAmount": 199900,
        "containerId": "comfino-paywall-container"
    }
</script>
<script src="https://sdk.craty.pl/checkout/v1/comfino-paywall.min.js"></script>

Paywall — Level B (SDK API)

const sdk = (await import('https://sdk.craty.pl/sdk/v1/comfino-sdk.min.js')).getComfinoSDK();

sdk.init({ platform: 'generic', environment: 'sandbox' });

sdk.createPaywall({
    authToken: '<AUTH_TOKEN_FROM_YOUR_BACKEND>',
    loanAmount: 199900,             // grosze
    platform: 'generic',
    containerId: 'comfino-paywall-container',
    onUpdateOrderPaymentState: (params) => {
        // The shopper picked an offer — persist params to your checkout / order.
        console.log('Selected loan:', params);
    }
});

Widget — Level A (config bridge)

<div id="comfino-widget"></div>

<script type="application/json" id="comfino-widget-config">
    {
        "sdkScriptUrl": "https://sdk.craty.pl/sdk/v1/comfino-sdk.min.js",
        "environment": "sandbox",
        "widgetKey": "<YOUR_WIDGET_KEY>",
        "priceSelector": ".product-price",
        "widgetTargetSelector": "#comfino-widget",
        "price": 199900
    }
</script>
<script src="https://sdk.craty.pl/product/v1/comfino-widget.min.js"></script>

Widget — Level B (SDK API)

const sdk = (await import('https://sdk.craty.pl/sdk/v1/comfino-sdk.min.js')).getComfinoSDK();

sdk.init({ platform: 'generic', environment: 'sandbox', widgetKey: '<YOUR_WIDGET_KEY>' });

const widget = sdk.bootstrapWidget({
    widgetKey: '<YOUR_WIDGET_KEY>',
    container: '#comfino-widget',
    widgetTargetSelector: '#comfino-widget',
    priceSelector: '.product-price',
    price: 199900 // Grosze — fallback if the selector finds nothing
});

The full walk-through, including how your backend generates the paywall authToken, is in docs/getting-started.md.

Run the full demo

Prefer to see it working end-to-end? demo/ is a runnable PHP app covering both surfaces at both levels (config bridge + SDK API), plus token minting, order creation, and webhook verification via the public comfino/php-sdk / comfino/php-api-client libraries:

cd demo && cp .env.dist .env   # add your sandbox keys
./bin/run-demo                 # → http://localhost:8000

---

What you build vs. what Comfino provides

• Your backend issues the paywall authToken (a short-lived HMAC over the cart) via the Comfino REST API, and stores the shopper's chosen offer on the order. The SDK never talks to your backend.
• Your frontend renders the container(s), supplies the config, and (Level B) reacts to the onUpdateOrderPaymentState callback / SDK events.
• The SDK loads the secure iframe UI, handles the offer calculation, price tracking, and all cross-frame messaging.

---

Contents

Path	Description
docs/getting-started.md	End-to-end first integration (paywall + widget).
docs/api-reference.md	Full public SDK surface: functions, options, handles.
docs/custom-platform.md	Integrating a brand-new platform: custom adapter, renderer, price logic.
docs/events.md	SDK events, DOM events, and callbacks.
docs/troubleshooting.md	CSP, common errors, debugging.
snippets/	Minimal copy-paste HTML + a framework-agnostic CDN loader.
demo/	Runnable full-stack demo app (PHP backend + both surfaces, both levels).
examples/vanilla-js/	Runnable HTML page (paywall + widget).
examples/typescript/	Type-checked TypeScript integration.
types/	Hand-written .d.ts for the public SDK surface.

---

TypeScript types

npm install --save-dev github:comfino/web-frontend-sdk

// tsconfig.json
{ "compilerOptions": { "types": ["@comfino/web-frontend-sdk"] } }

The types describe the public surface (getComfinoSDK, ComfinoSDK, bootstrapPaywall, ComfinoGenericPaywallConfig, ComfinoGenericWidgetConfig, the option/handle/renderer interfaces). See types/.

---

License

BSD-3-Clause