Checkout

createCheckout accepts five command variants and returns a local checkout ID, pending status, and provider URL.

type	Use when
single	The item is defined inline and needs no reusable catalog
catalog	A persisted priceId selects product, tier, and billing
offer	An exact registered offer key and revision selects terms
subscription_renewal	An existing manual subscription starts another period
invoice	A finalized metered invoice requires payment

Offer checkout

import { createCheckout } from "@byfungsi/sapa";

const program = createCheckout({
  type: "offer",
  offerKey: "workspace.pro",
  offerRevision: 1,
  quantity: 5,
  provider: "midtrans",
  customer: {
    externalId: "customer-42",
    email: "owner@example.com",
    name: "Workspace Owner",
  },
  beneficiary: { type: "merchant_subject", subjectId: "workspace-42" },
  successUrl: "https://merchant.example/billing/success",
  cancelUrl: "https://merchant.example/billing/cancel",
  clientIp: null,
  idempotencyKey: "workspace-42-pro-checkout-1",
});

quantity must be non-null only when the offer supports buyer-selected seats. Omitting beneficiary grants benefits to the paying customer.

Retained local state

After creation, persist the returned checkoutId with your order. Use getCheckout(checkoutId) to read the current local state. The state may be pending, succeeded, failed, or expired.

Recovery is reconciliation only

If provider creation has an unknown outcome, call recoverCheckout(checkoutId). Recovery can reconcile retained evidence but never creates another provider checkout. Never switch to a new idempotency key after a timeout merely to “try again.”

Security boundary

Create checkout from authenticated server code. Derive customer and beneficiary identities from trusted application state; do not accept arbitrary identities from a browser without authorization.

Continue with payments and refunds.