@apiosk/checkout-web

@apiosk/checkout-web

Framework-agnostic checkout button for plain HTML, server-rendered websites, and apps that want a custom element instead of a framework-specific SDK.

This package ships:

• the <apiosk-checkout-button> custom element
• a four-layer checkout flow
• rail selection and hosted checkout launch handling
• a thin contract on top of @apiosk/checkout-core

Install

After publish:

npm install @apiosk/checkout-web

Before publish:

npm install ./subs/checkout-web

HTML quick start

<apiosk-checkout-button id="checkout"></apiosk-checkout-button>

<script type="module">
  import { registerApioskCheckoutButton } from "@apiosk/checkout-web";

  registerApioskCheckoutButton();

  document.getElementById("checkout").config = {
    merchantName: "Northstar Marketplace",
    productName: "Automation bundle",
    amountLabel: "24.95 EUR",
    orderReference: "ord_2048",
    subtitle: "One trigger for human checkout and programmable payment rails.",
    rails: [
      { id: "credits", status: "live", launchUrl: "https://gateway.apiosk.com/geocode/forward" },
      { id: "x402", status: "live", launchUrl: "https://gateway.apiosk.com/geocode/forward" },
      { id: "agent", status: "pilot" }
    ],
    callbacks: {
      successUrl: "https://merchant.example/success",
      cancelUrl: "https://merchant.example/cancel",
      webhookUrl: "https://merchant.example/webhooks/apiosk",
      statusUrl: "https://merchant.example/api/orders/ord_2048"
    }
  };
</script>

JS API

import {
  createCheckoutButton,
  registerApioskCheckoutButton,
} from "@apiosk/checkout-web";

registerApioskCheckoutButton();

const button = createCheckoutButton({
  merchantName: "Apiosk Checkout",
  productName: "Geocode /forward",
  amountLabel: "0.01 USDC",
  orderReference: "intent_live_geocode_forward",
  rails: [
    { id: "credits", status: "live", launchUrl: "https://gateway.apiosk.com/geocode/forward" },
    { id: "x402", status: "live", launchUrl: "https://gateway.apiosk.com/geocode/forward" }
  ]
});

document.body.append(button);

Current contract

This package is intentionally opinionated:

• Layer 1: intent
• Layer 2: merchant review
• Layer 3: rail selection
• Layer 4: hosted launch

The launch step opens the configured rail launchUrl in a new tab. When the merchant intent API lands, the button should keep the same config contract and only change what the launch target points at.

When to use this package

Use @apiosk/checkout-web when:

• you want a plain HTML integration
• you need a checkout element inside non-React apps
• you want React and Vue wrappers to share the same runtime surface

Use @apiosk/checkout-core directly when you only need the contract and no UI.