Docs

Architecture

The app-developer architecture for ATM checkout, app callbacks, AT Protocol records, and private payment state.

Closed beta@atmosphere-money/app-nodeSDK beta: 0.0.0-beta.0ATM API beta: 2026-0642 lexicons

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

System map

ATM sits between AT Protocol apps and payment rails. Apps own the product experience and fulfillment. ATM owns checkout, payment state, app-scoped events, and the public proof bridge.

Your code

App

  • Product or event UI
  • App order state
  • Fulfillment
  • Webhook/XRPC receiver
Broker + control plane

ATM

  • Hosted checkout
  • Payment ledger
  • App events
  • Dashboard
Portable public layer

AT Protocol

  • DIDs and handles
  • Catalog records
  • attested.network records
  • AppView reads
Private rail

Processor

  • Payment method collection
  • Connected accounts
  • Refunds and disputes
  • Tax/reporting surfaces

Request paths

  1. 1

    App server

    Check recipient payability and create app order context.

  2. 2

    App server

    Mint app service-auth and call ATM initiate with an opaque checkout envelope.

  3. 3

    ATM checkout

    Create the payment session and redirect the buyer to hosted checkout.

  4. 4

    Processor

    Collect card, Link, Apple Pay, Google Pay, or another explicitly enabled method.

  5. 5

    ATM

    Record the settled payment, emit app events, and update proof-writing jobs.

  6. 6

    App receiver

    Verify the webhook or XRPC callback, deduplicate delivery, and fulfill.

What each layer owns

App UISelection, product pages, event pages, checkout buttons, post-payment UX, and order detail surfaces.
App serverPrivate fulfillment state, app order ids, inventory that is app-owned, webhook handling, and idempotent side effects.
ATM checkoutCheckout session lifecycle, wallet eligibility, processor session creation, receipt hooks, app events, and payment status.
ATM dashboardApp config, test/live environments, webhook logs, module settings, payments, subscriptions, reports, and developer tools.
Protocol recordsPortable product/catalog facts, public payment/proof facts, and safe strongRefs. Never raw customer or processor data.
ProcessorPayment method collection, connected-account requirements, charge details, disputes, fees, tax/reporting, and payout surfaces.

Data boundaries

Public PDS

  • money.atmosphere.product
  • money.atmosphere.price
  • network.attested.payment.*
  • safe entitlement refs

ATM private state

  • checkout_sessions
  • payments
  • subscriptions
  • proof_write_jobs
  • webhook deliveries

App private state

  • app order ids
  • fulfillment data
  • downloads
  • DM/order workflow
  • receiver idempotency

Never public

  • emails and addresses
  • processor account ids
  • payment method details
  • ticket QR secrets
  • attendee answers

Reference app

Supper is the working reference app for ATM payment integration. It demonstrates payability checks, hosted checkout, product/catalog links, subscriptions, app events, profile-driven UX, and support feed updates without making Supper-specific data part of ATM's public protocol records.

Tips and support

Use hosted ATM checkout and fulfill from payment.completed.

Products and commissions

Use ATM product refs for shared catalog fields and app-private fulfillment for Supper order state.

Subscriptions

Use one active support subscription per payer, recipient, and app.

Attestations

Write or reconcile proof state without asking buyers to re-auth during checkout when a buyer assertion is available.

Tickets boundary

Ticket-specific integration details live on atmosphere.tickets. ATM docs cover payment, app configuration, app events, and the shared dashboard model. Tickets docs cover scarcity, holds, issuance, QR/pass tokens, verification, and check-in.

Architecture - Atmosphere Money Docs