@cauril/checkout-js

Embedded checkout drop-in for the Cauril payments API. Renders a payment form in your page, lets the buyer pay with the methods you enabled, and routes the underlying PSP for you.

Browser-only. Zero runtime dependencies — the PSP's own SDK is loaded on demand at runtime. Card data is entered in the PSP's element and tokenized client-side; it never touches your servers or Cauril (PCI SAQ-A).

npm install @cauril/checkout-js

Or load it straight from the CDN (no build step):

<script src="https://js.cauril.com/v1/checkout.js"></script>

How it works

1. On your server, create a checkout session with the @cauril/node SDK and send its client_secret to the browser:

   const session = await cauril.checkout.sessions.create({
     amount: 5000, // minor units (cents)
     currency: "BRL",
     success_url: "https://shop.example/thanks",
     cancel_url: "https://shop.example/cart",
   });
   // → send session.client_secret to the client

2. In the browser, mount the drop-in with that client_secret:

   import { Cauril } from "@cauril/checkout-js";
   // or, via the CDN <script>, use the global `Cauril`
   
   const checkout = Cauril.checkout({
     clientSecret, // from your server, never a secret API key
     appearance: { theme: "light", accent: "#0a7", radius: 8 },
   });
   
   checkout.on("completed", ({ payment_status }) => {
     window.location.href = "/thanks";
   });
   checkout.on("failed", ({ code, message }) => showError(message));
   
   await checkout.mount("#cauril-checkout");

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

Options

Cauril.checkout({
  clientSecret,                 // required — from POST /v1/checkout/sessions
  baseUrl: "https://api.cauril.com", // default
  locale: "es" | "pt" | "en",   // overrides the session/browser locale
  appearance: {                 // controlled theming only (sanitized; no arbitrary CSS)
    theme: "light" | "dark",
    accent: "#0a7",             // primary-button color
    radius: 8,                  // px, clamped 0–24
    font: "system" | "serif" | "mono",
  },
  onComplete: "manual" | "redirect", // "manual" (default) emits `completed`; "redirect" navigates to success_url
});

Events

checkout.on(event, handler) returns an unsubscribe function.

| Event | Payload | |---|---| | ready | { session } — the public session loaded | | method_selected | { method } | | processing | — | | requires_action | { next_action } — e.g. 3DS / voucher / redirect | | completed | { payment_status } | | failed | { code, message } | | expired | — | | error | { code, message } |

A listener that throws never breaks the payment flow.

Notes

• The buyer chooses a payment method (card, pix, wallet, …), never a processor — Cauril routes the PSP behind the scenes.
• clientSecret is a per-session token, safe to expose to the browser. It is not an API key.
• Full guides and API reference: cauril.com/docs.