Embed checkout on your site

​

1. Install the SDK

npm install @kelviq/js-checkout

import { open, embed } from '@kelviq/js-checkout';

<script src="https://cdn.jsdelivr.net/npm/@kelviq/js-checkout@1/dist/kelviq.js"></script>

​

2. Create a checkout session

curl -X POST https://api.kelviq.com/api/v1/checkout/ \
  -H "Authorization: Bearer $KELVIQ_SERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planIdentifier": "pro",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789"
  }'

{
  "checkoutUrl": "https://checkout.kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
  "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
}

​

3. Open checkout

<button id="buy">Buy Pro</button>

<script>
  document.getElementById('buy').addEventListener('click', async () => {
    // Your backend creates the session and returns { checkoutUrl }
    const { checkoutUrl } = await fetch('/api/checkout', { method: 'POST' })
      .then((r) => r.json());

    Kelviq.open({
      url: checkoutUrl,
      onSuccess: (order) => {
        console.log('Paid', order.orderId, order.planName);
      },
      onClose: () => {
        console.log('Checkout closed');
      },
    });
  });
</script>

<div id="checkout"></div>

<script>
  const handle = Kelviq.embed({
    url: checkoutUrl, // from your backend
    container: '#checkout',
    onSuccess: (order) => {
      console.log('Paid', order.orderId);
    },
  });

  // In a single-page app, unmount when the user navigates away:
  // handle.destroy();
</script>

​

Options

​

Color mode (theme)

Kelviq.open({
  url: checkoutUrl,
  theme: document.documentElement.classList.contains('dark') ? 'dark' : 'light',
});

​

Callbacks

​

Overlay options (Kelviq.open only)

​

Handles

const overlay = Kelviq.open({ url });   // { close(), update() }
const inline = Kelviq.embed({ url, container }); // { destroy(), update() }

​

Change the plan from your page (update)

const inline = Kelviq.embed({ url: checkoutUrl, container: '#checkout' });

document.querySelector('#yearly').addEventListener('change', (event) => {
  inline.update({ chargePeriod: event.target.checked ? 'YEARLY' : 'MONTHLY' });
});

• Values must exist on the session: a plan from the offering and one of its enabled billing periods. The checkout ignores anything else.
• If you change only the period and the current plan has no price for it, the checkout picks the first plan that does, as its own period tabs do.
• Calls made before onLoaded are queued and applied once the checkout has loaded.
• To hide the checkout’s own plan selector and keep yours as the single source of truth, create the session with plansEnabled: false.

​

Use with a framework

import { useEffect, useRef } from 'react';
import { embed, open } from '@kelviq/js-checkout';

// Inline checkout on a dedicated page
export function InlineCheckout({ url }: { url: string }) {
  const container = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!container.current) return;
    const handle = embed({
      url,
      container: container.current,
      onSuccess: (order) => console.log('paid', order.orderId),
    });
    return () => handle.destroy();
  }, [url]);

  return <div ref={container} />;
}

// Overlay from a button
export function BuyButton({ url }: { url: string }) {
  return <button onClick={() => open({ url })}>Buy</button>;
}

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue';
import { embed, type KelviqEmbedHandle } from '@kelviq/js-checkout';

const props = defineProps<{ url: string }>();
const container = ref<HTMLElement>();
let handle: KelviqEmbedHandle | undefined;

onMounted(() => {
  handle = embed({ url: props.url, container: container.value! });
});
onBeforeUnmount(() => handle?.destroy());
</script>

<template><div ref="container" /></template>

​

Success callback or redirect

​

Sandbox

​

Browser support

• Your page (the SDK): every browser Stripe.js supports, including Chrome 38+, Safari 10.1+, Firefox 29+, Edge 15+, iOS Safari 9+ and Android Chrome 38+. The script never breaks the host page on an unsupported browser.
• The checkout inside the frame: Chrome and Edge 99+, Firefox 97+, Safari 15.4+. On older browsers the customer sees a “browser not supported” message instead of the form, and onClose still fires if they dismiss it.

​

Limitations

• Static checkout links (https://www.kelviq.com/buy/…) cannot be embedded yet. Create a session with the Checkout API and embed its checkoutUrl.
• Redirect-based payment methods such as iDEAL and Bancontact are not supported in embedded mode. Card payments, including 3D Secure challenges, work.
• Kelviq controls which sites may frame the checkout. If your embed renders blank and the browser console reports a frame-ancestors violation, contact hi@kelviq.com with the domain you embed from.

​

Troubleshooting