Checkout widget

The checkout widget is a small script that completes a payment session in the customer's browser. It is the only client library. For your server, call the HTTP API directly: no libraries for Node.js, Python, Ruby, PHP or Go have been published.

How it works

The widget needs no secret and it cannot set the amount. The amount, currency and account are fixed when your server creates the session.

1. Your server calls POST /payment-sessions with a secret key (sk_...) and gets back id, client_secret, amount and currency.
2. Your page gives the session id and client_secret to the widget, together with your publishable key (pk_...).
3. The widget collects the card with Stripe and confirms the session. A publishable key can only read and confirm a payment session.

Installation

Version 2 is served from its own path. A page that loads v2 is not changed by later releases of another major version.

<script src="https://cdn.cari.finance/js/v2/cari-finance.min.js"></script>

Basic usage

const cariFinance = new CariFinance("pk_test_YOUR_PUBLISHABLE_KEY");

cariFinance.mountCheckout("#checkout", {
   sessionId: "ps_...", // from your server
   clientSecret: "...", // from your server
   onSuccess: (result) => console.log("Paid", result.charge_id),
   onError: (error) => console.error(error.message),
});

Rules the widget enforces

• A secret key (sk_...) is refused in the browser with the error code secret_key_in_browser.
• confirmPayment has no amount parameter. The charge is the session's amount.
• The publishable key's mode (pk_test_ or pk_live_) must match the session's livemode, or the widget stops with mode_mismatch.
• Card details go to Stripe.js. They do not reach your page's code or Cari Finance.
• If the answer is "still processing" (HTTP 202), the widget does not report a failure and does not say the customer was not charged, because that is not known yet.

Lower level calls

If you build your own form, call these directly:

const session = await cariFinance.retrieveSession(sessionId, clientSecret);
// { status, amount, currency, livemode }

const result = await cariFinance.confirmPayment({
   sessionId,
   clientSecret,
   paymentMethodToken, // a Stripe card token you created yourself
   receiptEmail: "customer@example.com",
});
// { status, charge_id }