Kalixo.js

Kalixo.js renders the payment form for a checkout session. Kalixo decides which payment form to show, so your integration never changes when Kalixo changes providers.

Load Kalixo.js

Always load Kalixo.js from js.kalixo.io. Do not bundle or self-host it: Kalixo ships security fixes and new payment methods through this URL.

<script src="https://js.kalixo.io/v1/kalixo.js"></script>

import { loadKalixoCheckout } from '@kalixo/checkout-js';

const KalixoCheckout = await loadKalixoCheckout();

To pin a release, load https://js.kalixo.io/v1/<version>/kalixo.js with the integrity hash from the release notes.

Mount the checkout

const kalixo = await KalixoCheckout.init({ publishableKey: 'kc_pk_live_...', locale: 'nl-NL' });
const checkout = kalixo.checkout({ sessionId, clientSecret });

checkout.on('ready', () => hideSpinner());
checkout.on('payment.completed', ({ sessionId }) => {
  window.location.assign(`/checkout/complete?session_id=${sessionId}`);
});
checkout.on('payment.processing', () => showMessage('We are confirming your payment.'));
checkout.on('payment.failed', ({ message }) => showError(message));
checkout.on('error', ({ message }) => showError(message));

await checkout.mount('#kalixo-checkout');

If you do not listen to payment.completed, Kalixo.js redirects the shopper to the session’s return_url with ?session_id=cs_....

Browser events are for the shopper experience only. Never fulfil from payment.completed, a return_url redirect, or checkout_session.status. Confirm on your server with GET /v1/payments/{id} or the payment.captured webhook, and refuse the order if amount_mismatch is true.

Events

Event	When
`ready`	The payment form is shown
`payment.completed`	The payment was authorised
`payment.processing`	The outcome is pending (for example a bank transfer); you get a webhook later
`payment.failed`	The payment was declined. `message` is safe to show to the shopper
`error`	The checkout could not load or the session is no longer open (`code: session_complete`, `session_expired`)

Styling

Pass theme tokens; do not style the inner form with your own CSS selectors.

kalixo.checkout({
  sessionId,
  clientSecret,
  theme: { colors: { primary: '#0a7cff', text: '#1d2433' }, radius: '8px', font_family: 'Inter, sans-serif' },
});

Kalixo can also set default theme tokens for your account.

Redirect payment methods

Some payment methods send the shopper to their bank. The bank returns the shopper to Kalixo, and Kalixo forwards them to your return_url with ?session_id=cs_.... Read the payment on your server to show the result.

Content Security Policy

If your checkout page uses a CSP, it must allow Kalixo.js, the Kalixo API and the secure payment fields that Kalixo.js loads:

script-src https://js.kalixo.io;
connect-src https://checkout.kalixo.io https://sandbox.checkout.kalixo.io;
frame-src https:;
style-src 'unsafe-inline';
img-src data:;

The secure payment fields need a few more domains. Ask Kalixo integrations at [email protected] for the complete policy for your account. Kalixo tells you about changes to it before they are needed.

PCI DSS

Card details are entered in secure fields that Kalixo.js loads from the payment provider. Card data never touches your page or Kalixo’s servers, which keeps your PCI scope at SAQ A, provided you load Kalixo.js from js.kalixo.io.

Get started

Accept payments

After the payment

Core concepts

Load Kalixo.js

Mount the checkout

Events

Styling

Redirect payment methods

Content Security Policy

PCI DSS

​Load Kalixo.js

​Mount the checkout

​Events

​Styling

​Redirect payment methods

​Content Security Policy

​PCI DSS

Load Kalixo.js

Mount the checkout

Events

Styling

Redirect payment methods

Content Security Policy

PCI DSS