billing.js

Embed billing.io checkout directly into your website. Your customers pay without leaving your page.

How it works

Your backend                     Your frontend
────────────                     ─────────────
                                 Customer clicks "Pay"
                                        │
POST /v1/checkouts  ◄───────────────────┘
(with your secret key)
        │
        ▼
Returns checkout ID ────────────►  billing.openCheckout({
(e.g. "co_abc123")                   checkoutId: "co_abc123"
                                   })
                                        │
                                        ▼
                                 Overlay opens on your page
                                 Customer pays
                                        │
                                        ▼
                                 onSuccess callback fires

Your backend creates a checkout using your secret API key. Your frontend opens it in an overlay using just the checkout ID. No API keys are exposed in the browser.

Quick start

1. Create a checkout (server-side)

Use your secret key to create a checkout from your backend. Never expose your secret key in frontend code.

Node.js

import { BillingIO } from "@billing-io/sdk";

const billing = new BillingIO({ apiKey: "sk_live_..." });

// In your API route / server action
const checkout = await billing.checkouts.create({
  amount_usd: 20.00,
  chain: "tron",       // "tron" or "arbitrum"
  token: "USDT",       // "USDT" or "USDC"
});

// Return checkout.checkout_id to your frontend

cURL

curl -X POST https://api.billing.io/v1/checkouts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount_usd": 20.00, "chain": "tron", "token": "USDT" }'

2. Add billing.js to your page (client-side)

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

3. Open the checkout overlay

Pass the checkout ID from your backend — no API key needed on the frontend.

billing.openCheckout({
  checkoutId: "co_abc123",
  onSuccess: ({ checkoutId, txHash }) => {
    // Payment confirmed on-chain
  },
  onClose: () => {
    // Customer closed without paying
  },
});

Full example

<button id="pay-btn">Pay $20</button>

<script src="https://js.billing.io/v1/billing.js"></script>
<script>
  document.getElementById("pay-btn").addEventListener("click", async () => {
    // 1. Create checkout via your backend
    const res = await fetch("/api/create-checkout", { method: "POST" });
    const { checkoutId } = await res.json();

    // 2. Open the overlay
    billing.openCheckout({
      checkoutId,
      variation: "centered",
      onSuccess: ({ txHash }) => {
        window.location.href = "/thank-you";
      },
      onClose: () => {
        console.log("Customer closed checkout");
      },
      onError: (err) => {
        console.error(err.message);
      },
    });
  });
</script>

Your /api/create-checkout backend route would create the checkout with your secret key and return the ID. See the server-side SDKs for language-specific guides.

Checkout variations

Control how the checkout appears on your site with the variation option.

| Variation | Name | Best for | |-----------|------|----------| | "centered" | Centered Card | Desktop-first sites, general purpose (default) | | "panel" | Side Panel | Dashboards, SaaS apps, settings pages | | "bottom" | Bottom Sheet | Mobile-first sites, responsive apps | | "fullscreen" | Fullscreen | High-value purchases, focused checkout flows | | "popup" | Floating Popup | Minimal disruption, e-commerce sidecarts |

billing.openCheckout({
  checkoutId: "co_abc123",
  variation: "panel",
});

Centered Card (default)

Classic modal centered on screen with a blurred backdrop. Familiar pattern that works everywhere.

Side Panel

Slides in from the right edge. The customer can still see your page content on the left — useful when context matters (order summaries, dashboards).

Bottom Sheet

Rises from the bottom with a drag handle. Feels native on mobile devices. Great for responsive sites that need to work well on both phone and desktop.

Fullscreen

Takes over the entire viewport with a branded top bar. Removes all distractions — the customer focuses entirely on completing payment. Best for high-value or subscription checkouts.

Floating Popup

Compact card that appears in the bottom-right corner. Least disruptive — your page stays fully visible. Good for quick add-on purchases or tipping flows.

API reference

billing.openCheckout(options)

Opens the checkout overlay.

| Option | Type | Required | Description | |--------|------|----------|-------------| | checkoutId | string | Yes | Checkout ID from your backend (e.g. "co_abc123") | | variation | string | No | Overlay style: "centered", "panel", "bottom", "fullscreen", "popup". Defaults to "centered". | | onSuccess | function | No | Called when payment is confirmed. Receives { checkoutId, txHash }. | | onClose | function | No | Called when the customer closes the overlay without completing payment. | | onError | function | No | Called on error. Receives { message, code }. |

billing.redirectToCheckout(options)

Redirects to the full-page hosted checkout instead of using an overlay. Use when you prefer a separate checkout page.

billing.redirectToCheckout({ checkoutId: "co_abc123" });

billing.close()

Closes the overlay programmatically.

Callbacks

onSuccess({ checkoutId, txHash })

Fires when the payment is confirmed on-chain. The overlay auto-closes shortly after to show a confirmation state.

• checkoutId — the checkout that was paid
• txHash — blockchain transaction hash (may be null if not yet available)

onClose()

Fires when the customer dismisses the overlay (backdrop click, Escape key, or close button). Does not fire after a successful payment auto-close.

onError({ message, code })

Fires if the checkout encounters an error (network failure, expired checkout, invalid ID, etc.).

Overlay behavior

• Scroll lock — Page scrolling is disabled while the overlay is open.
• Escape key — Closes the overlay and fires onClose.
• Backdrop click — Closes the overlay and fires onClose.
• Reopen — Calling openCheckout with the same checkout ID while open brings the existing overlay to the front. A different ID replaces it.
• Auto-close — After a successful payment, the overlay closes automatically after a brief confirmation.

Self-hosting

billing.js auto-detects the billing.io host from its own script URL. If you're self-hosting, set the host explicitly:

<script src="/v1/billing.js" data-host="https://billing.yourdomain.com"></script>

Security

• No API keys in the browser. billing.js only needs a checkout ID — your secret key stays on your server.
• Checkout IDs are single-use. Each ID maps to one payment with a fixed amount, chain, and expiration. They can't be reused or modified.
• Iframe sandboxing. The checkout runs in a sandboxed iframe with restricted permissions.
• PostMessage validation. All communication between the overlay and the checkout page uses namespaced message events.

Browser support

All modern browsers — Chrome, Firefox, Safari, Edge. No build step, no dependencies, no framework required.

License

MIT