Docs

App onboarding

A practical zero-to-first-checkout guide for app developers setting up ATM modules, webhooks, environments, and test events.

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

Choose your integration

Start from the shape of your app. The ATM dashboard can expose payments, products, subscriptions, tickets, and future machine payment modules without forcing each app to become a payment platform.

Closed betaDocs draftMore modules later

Creator app

Use hosted checkout, app webhooks, catalog products, and subscription settings.

Ticketing app

Enable Tickets, use availability and holds, and keep event UX in your app.

Scanner app

Use opaque ticket tokens, verify before entry, and make check-in idempotent.

Agent or tool

Use service-auth, idempotent event handling, and documented spend/receipt boundaries.

1. Register the app

01
Sign in as the app DID
The app account is still an ATM profile with avatar, name, and description.
02
Request app role
Closed beta app registration is allowlisted while contracts settle.
03
Add app URL
This gives users and operators a stable app identity in dashboard surfaces.
04
Open test environment
Test mode is the default place to configure modules and receivers.

2. Configure modules

Payments	Hosted checkout, app fee routing, payment rows, receipts, refunds, and app events.
Products	ATM catalog product/price refs plus app-private fulfillment links.
Subscriptions	Durable recurring relationships with app-configurable subscription behavior.
Tickets	Availability, holds, free claims, issued tickets, QR/pass tokens, and check-in.
Machine payments	Future MPP/x402-style module; visible as roadmap, disabled for launch.

3. Add receivers

Configure an HTTP webhook first. Add an XRPC receiver only if your app already exposes an AT Protocol-native service surface.

txt

HTTP webhook
  app config: https://app.example/api/atm/webhook
  auth: ATM signature over raw body

XRPC receiver
  app service: https://app.example/xrpc/money.atmosphere.event.receive
  auth: ATM service-auth to app

4. Send test events

Use the app dashboard to send test events before real checkout. Store delivery ids and make your handler safe to redrive.

Send payment.completed test event.
Send subscription.updated test event if subscriptions are enabled.
Send product.archived test event if catalog is enabled.
Send tickets.issued test event if Tickets is enabled.
Force a failed delivery and redrive it after fixing the receiver.

5. Run first checkout

Create a private app order, call payout status, start ATM checkout, and fulfill only when ATM confirms the payment.

curl https://checkout.atmosphere.money/xrpc/network.attested.payment.initiate \
  -H "Authorization: Bearer $APP_SERVICE_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"product":"atm.checkout.v1:<private-envelope>"}'

6. Production review

Production access should confirm the app uses the correct environment, has tested receiver redrive, keeps private data off protocol, and has clear user-facing failure states.

App profile and contact details are complete.
Live webhook/XRPC receiver is configured and tested.
App fee and optional ATM support share are intentional.
Payment setup states are disabled before recipients are payable.
Privacy, terms, and support routes are visible before launch.