Pricing & Portal SDK

Sell subscriptions from your own website. Two building blocks make it work:

1. Public Catalog API — a read-only, browser-safe API that serves your plans, products and branding with a publishable key. Render your pricing table from live data; change a price in one place and your site follows.
2. Portal JS SDK — a single script from cdn.lunixi.com that takes a visitor from "pick a plan" to "card saved, subscription active". Use the ready-made portal UI, go fully headless against your own components, or mix both.

No redirect to an external checkout. Card data is collected in the SDK's secure form and never touches your server.

How the pieces fit

• Before sign-up the visitor only needs prices: the catalog layer, keyed by your publishable key.
• At subscribe time the visitor becomes a customer: your backend bootstraps an SDK session for that customer, and the browser SDK finishes the job — or your backend creates the subscription itself via the Merchant API.

Layer 1 — Public Catalog API

Read-only endpoints designed to be called directly from the browser:

Authentication: publishable key + Origin allow-list

Catalog calls authenticate with your publishable key (mk_live_pk_…) in the Authorization header. It is safe to embed in client-side code — it can only read the public catalog, never move money or expose customer data.

Two switches gate the whole surface, both managed from the merchant panel (Portal → SDK settings):

• Origin allow-list — add every origin that will call the API (e.g. https://www.example.com). Requests from unlisted origins are rejected.
• SDK enabled — the master toggle for the embedded surface.

Request

curl "https://api-gateway.lunixi.com/api/public/v1/subscription/plans?locale=en" \
  -H "Authorization: Bearer mk_live_pk_xxxxxxxxxxxx" \
  -H "Origin: https://www.example.com"

The locale parameter returns catalog translations — send locale=tr and localized names and descriptions come back where you defined them.

Response

Plans come back in a data array, with nextPageToken for cursor pagination:

{
  "success": true,
  "data": [
    {
      "id": "pln_9f3a1c",
      "productId": "prd_4b2e88",
      "code": "pro-monthly",
      "name": "Pro Monthly",
      "description": "For growing teams",
      "price": 49900,
      "currency": "TRY",
      "trialPeriodDays": 7,
      "billing": { "frequency": "MONTHLY", "interval": 1 }
    }
  ],
  "nextPageToken": ""
}

Layer 2 — Portal JS SDK

One script, four modes:

<script src="https://cdn.lunixi.com/lunixi-portal.min.js"></script>

Mode 0 — pricing data, zero backend

const catalog = Lunixi.portal.catalog({
  publishableKey: 'mk_live_pk_xxxxxxxxxxxx',
  locale: 'en',
});
 
const plans    = await catalog.plans();     // all active plans
const products = await catalog.products();  // all active products
const branding = await catalog.branding();  // logo, colors, terms URLs

This is the same Public Catalog API, wrapped — ideal for rendering the pricing table before the visitor has signed in anywhere.

Session bootstrap — your backend mints the session

Modes 1–3 act on behalf of a specific customer, so they need a session that only your backend can create. The browser never sees your secret key; it receives a short-lived, origin-bound session instead.

POST /api/v1/subscriptions/portal/sdk-session — Bearer (at_live_…), server-to-server only:

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/portal/sdk-session \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "origin": "https://www.example.com",
    "sdkMode": "HYBRID"
  }'

The response — { portalToken, sessionProof, proofNonce, proofExpiresAt } — is handed to the browser SDK. The requested origin must be on your allow-list, and sdkMode must be among the modes you enabled in the panel.

The simplest wiring: give the SDK the URL of your bootstrap endpoint and let it fetch the session itself:

const portal = Lunixi.portal.create({
  sessionBootstrapUrl: '/portal-session', // your backend endpoint from above
});
await portal.init(); // validates the session, loads branding & permissions

Mode 1 — drop-in portal UI

<div id="portal"></div>
<script>
  Lunixi.portal.mount('#portal', {
    sessionBootstrapUrl: '/portal-session',
    locale: 'en',
  });
</script>

Renders the full self-service portal — plans, active subscription, invoices, card management — styled with the branding you configured. One div, done.

Mode 2 — headless

Every portal capability as plain async methods; you render everything:

const portal = Lunixi.portal.create({ sessionBootstrapUrl: '/portal-session' });
await portal.init();
 
// The customer proves ownership with a one-time code (email/SMS):
await portal.requestOtp();
await portal.verifyOtp(codeFromInput);   // → session JWT held inside the client
 
const me      = await portal.me();
const plans   = await portal.plans();
const subs    = await portal.subscriptions();
const invoices = await portal.invoices();
 
// Start a subscription with a saved card / card token:
await portal.startSubscription({
  planId: selectedPlan.id,
  paymentMethodToken: cardToken,
});

Mode 3 — hybrid widgets

Keep your own page layout, borrow only the hard parts:

// A ready-made plan picker inside your layout:
Lunixi.portal.plans.mount('#plans', {
  sessionBootstrapUrl: '/portal-session',
  onSelect: (plan) => showCheckout(plan),
});
 
// The PCI-safe card form — card data never touches your code:
Lunixi.portal.cardForm.mount('#card', {
  sessionBootstrapUrl: '/portal-session',
  onSuccess: (cardToken) => subscribe(cardToken),
});

The card form is the piece you should never rebuild yourself: it collects the PAN inside the SDK's secure context and hands you back only a token.

End to end: pricing table → plan → active subscription

const catalog = Lunixi.portal.catalog({ publishableKey: 'mk_live_pk_xxxxxxxxxxxx' });
const [plans, branding] = await Promise.all([catalog.plans(), catalog.branding()]);
 
for (const plan of plans) {
  renderPlanCard(plan, {
    onSubscribe: () => startSignup(plan), // ₺: format plan.price / 100
  });
}

Lunixi.portal.cardForm.mount('#card', {
  sessionBootstrapUrl: '/portal-session',
  onSuccess: (cardToken) => activate(plan, cardToken),
});

const portal = Lunixi.portal.create({ sessionBootstrapUrl: '/portal-session' });
await portal.init();
await portal.requestOtp();
await portal.verifyOtp(codeFromInput);
 
const sub = await portal.startSubscription({
  planId: plan.id,
  paymentMethodToken: cardToken,
});
// sub.status → provisioned the moment `subscription.activated` fires

Errors

Webhooks

Next steps

• Getting Started — the same chain, fully server-side
• Plans — trials, billing rules, dunning
• Customer Portal — hosted portal links, OTP flow, permissions
• Products — catalog translations for multi-language pricing pages