Docs

Checkout embed roadmap

Future plan for optional embedded ATM checkout while keeping hosted checkout, payment collection, and fulfillment truth under ATM.

Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.

Status

Hosted ATM checkout remains the universal launch path. Embedded checkout is a future optional UX layer for apps that want buyers to stay inside the app surface while ATM still owns payment collection, receipts, proof writes, and app events.

RoadmapHosted checkout fallbackDo not build against yet

Proposed package

The likely browser package is @atmosphere-money/checkout-embed. It should stay separate from @atmosphere-money/app-nodebecause the Node SDK handles app secrets, service-auth, webhook verification, and private checkout envelopes.

App Node SDK

Server-only checkout initiation, service-auth, webhooks, XRPC receivers, and Tickets helpers.

Checkout embed

Browser-only wrapper around an ATM-hosted checkout iframe or modal.

Supper widgets

Supper-owned creator buttons for personal sites, with Supper remaining the app.

Browser API sketch

import { mountAtmCheckout } from "@atmosphere-money/checkout-embed";

const checkout = mountAtmCheckout({
  container: "#atm-checkout",
  checkoutUrl,
  fallbackUrl: checkoutUrl,
  onStatus(event) {
    if (event.type === "completed") {
      showProcessingState();
    }
  }
});

checkout.open();

Message events

ready	The ATM iframe is loaded and can receive focus.
payment.started	The buyer has begun the payment form flow.
payment.processing	ATM is waiting on processor confirmation or post-payment work.
payment.completed	The browser flow reached a completed state; app fulfillment still waits for verified ATM events.
payment.failed	The current attempt failed or needs a new payment method.
checkout.cancelled	The buyer cancelled and should return to app UX.
checkout.fallback_required	The app should open the hosted checkout URL in top-level context.

Fallback rules

Wallet or payment method requires top-level browser context.
Browser blocks third-party storage or iframe payment flows.
The app CSP cannot safely frame checkout.
OAuth re-auth is needed.
The app iframe origin is not registered.
ATM detects an unsupported embedded flow.

Security boundary

postMessage events are UX signals only. Apps fulfill orders from verified webhooks, optional XRPC receiver events, or server-side ATM status reads. The embed cannot replace app webhook idempotency, payment status checks, or ticket issuance checks.

The full roadmap lives in docs/developer/CHECKOUT_EMBED_ROADMAP.md.