@apiosk/checkout-core

@apiosk/checkout-core

Shared checkout contract for all Apiosk checkout surfaces.

This package owns the schema and helper layer that the other checkout modules should agree on:

• rail metadata
• normalized checkout config
• checkout intent payload shape
• checkout status path helpers
• webhook event names
• webhook signature helpers

Install

After publish:

npm install @apiosk/checkout-core

Before publish:

npm install ./subs/checkout-core

What belongs here

checkout-core is not a UI package. It should stay framework-neutral and avoid React, Vue, DOM, and CSS concerns.

Use it when you need to:

• build a merchant checkout intent payload
• normalize rail configuration before rendering a button
• keep webhook naming and signature handling consistent
• share the same checkout schema between web, React, Vue, and server code

Quick start

import {
  createCheckoutIntentPayload,
  normalizeCheckoutConfig,
  selectDefaultRail,
} from "@apiosk/checkout-core";

const config = normalizeCheckoutConfig({
  merchantName: "Northstar Marketplace",
  productName: "Automation bundle",
  amountLabel: "24.95 EUR",
  orderReference: "ord_2048",
  rails: [
    { id: "credits", status: "live" },
    { id: "x402", status: "live" },
    { 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",
  },
});

const payload = createCheckoutIntentPayload(config);
const defaultRail = selectDefaultRail(config.rails);

Normalized config

The normalizer accepts both:

• a flat button-friendly shape like merchantName, productName, amountLabel
• a structured config with merchant, order, appearance, and callbacks

That lets internal dashboard code migrate incrementally while external SDKs use the structured version from day one.

Intent contract

createCheckoutIntentPayload() produces the payload shape that the future checkout API should accept at:

• POST /v1/checkout/intents
• GET /v1/checkout/intents/:id

This package is where that contract should evolve first.

Webhook helpers

Use createWebhookSignature() and verifyWebhookSignature() for server-side signature handling:

import { verifyWebhookSignature } from "@apiosk/checkout-core";

const rawBody = '{"event":"checkout.intent.paid"}';
const signature = request.headers["x-apiosk-signature"];

const isValid = await verifyWebhookSignature(
  rawBody,
  signature,
  process.env.APIOSK_WEBHOOK_SECRET,
);

Pass the raw request body string whenever possible.