JavaScript / Browser SDK

@lartech/infraio-checkout-js is the only SDK we publish today. It runs in the browser and opens our hosted checkout. Backend SDKs (Node, Go, Python) are on the roadmap; until then, talk to the gateway directly — see the Quickstart for a HMAC signing helper.

• Current version: 0.1.1-beta.17 (pre-1.0; expect minor breaks)
• Formats: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Types bundled (index.d.ts)
• Zero runtime peers — no React, jQuery, or other deps

Install

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Returns a Promise<InfraIoInstance>.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Optional. Override only when pointing at a non-prod environment.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Opens the hosted checkout. Returns void (use callbacks for state).

sdk.close()

Programmatically dismiss an open popup or embed. No-op for redirect mode.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// later, e.g. when user navigates away
sdk.close();

sdk.openRefundRequest({ … })

Opens the hosted refund-request form for a one-time token your backend minted via POST /b2b/v1/merchants/{merchant_id}/refund-requests. The buyer fills in their refund destination address + reason + (optional) metadata on our page; your page only handles the open/close lifecycle. Returns a close() function — call it to programmatically dismiss the popup or detach the embed iframe. In redirect mode the returned function is a no-op.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Mint the token server-side, then hand it to the SDK in the browser.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // Buyer submitted the form.
    // linkToken → /r/:linkToken status page (share with the buyer).
    // refundId  → use with B2B API to approve / reject.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* buyer closed without submitting */ },
});
 
// Programmatically dismiss the popup later if needed:
// close();

Token states surfaced via onError

If the buyer opens a stale token, the page itself handles the display (renders an “Expired — request new link” prompt, etc.), and the SDK does not fire onError for those cases — the buyer is inside the form flow and your code doesn’t need to react. onError only fires for things your code can act on (bad arguments, network failure loading the iframe).

Error class

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* bad sessionId / args */ break;
      case "iframe_load_error":       /* iframe failed to load */ break;
      case "iframe_timeout_error":    /* exceeded timeoutMs */ break;
      case "already_open_error":      /* another checkout is already open */ break;
      case "network_error":           /* transient network problem talking to the checkout origin */ break;
      case "api_error":               /* backend returned a non-2xx for an SDK-issued call */ break;
    }
  },
});

sdk.openRefundRequest() throws only invalid_request_error (missing or invalid token / args), synchronously. iframe_load_error (the refund-request iframe failed to load) is delivered asynchronously via onError, not thrown. It does not emit iframe_timeout_error or already_open_error — the refund-request popup has no load-timeout and allows multiple concurrent popups.

Mode notes

Popup

• Centered overlay with a dark semi-transparent backdrop
• z-index: 2147483647 (max int32) — sits above everything else
• Body scroll is locked while open; restored on close
• Close button gets initial focus; Tab is trapped in the popup
• Closed by: close button, Escape, click outside, sdk.close(). All of them call onCancel
• The checkout page can request resize via postMessage — the SDK clamps within width/height limits

Redirect

• Hard navigation via window.location.href
• Automatically appends ?return_url=<current-page> so the buyer returns where they came from. If your success_url / cancel_url on the session already cover this, the round-trip ignores return_url

Embed

• iframe with allow="payment; clipboard-write" (HTML5 Feature Policy directives — not the sandbox attribute). The iframe is served from the checkout origin, so wallet popups and clipboard writes from the buyer side work without further opt-in.
• Container width is 100%; height auto-sizes via INFRAIO_RESIZE postMessage, clamped [200, 2000]px
• No CSS isolation beyond the iframe boundary — your parent page styles do not bleed in
• Always wire onReady so you can hide your own loading state when the checkout becomes interactive

TypeScript

All types are bundled. Most useful exports:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION is the SDK’s own version string — useful in bug reports.

What’s next

• React / Vue framework wrappers — planned for the post-launch iteration once the vanilla JS surface stabilises across the pilot merchants. The vanilla SDK works fine inside React today; the wrappers will just remove the manual useRef + lifecycle plumbing.
• Cross-tab session resumption — open the checkout in tab A, finish in tab B. Useful when a buyer follows a magic-link mid-flow. Tracked for the next minor release.
• Theming via CSS variables — surface a small set of design tokens (radius, accent colour) on the iframe so merchants can match their brand without forking the page.
• Server-side helpers — a tiny @lartech/infraio-server package exposing verifyWebhook() + signedRequest() so backend code doesn’t need to copy the HMAC ritual. Until it ships, the signature verification page lists drop-in implementations in TypeScript, Go, Python, and Ruby.