Docs

Pilot playbooks

Concrete beta acceptance checklists for atmo.rsvp, plyr.fm, and future ATM app pilots.

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

Purpose

Pilot apps need a concrete acceptance path before live access. These checks cover the first event-ticketing app, the first music app, and future apps that use the same ATM surfaces.

Goal

Prove app registration, test-mode config, checkout, event delivery, fulfillment, refund/revoke, and dashboard visibility before live access.

Source of truth

Fulfillment comes from verified ATM webhooks, optional XRPC receiver events, or ATM status reads, never from browser redirects alone.

Sandbox only

Run every pilot in the ATM app test environment first. Live access should be a separate review after test evidence exists.

SDK discipline

Do not add broad SDK helpers until a pilot app hits real friction in at least one of these flows.

Shared sandbox packet

Give each pilot app the same minimal packet. The app-specific checklist can then focus on business behavior instead of setup vocabulary.

Install	npm install @atmosphere-money/app-node@beta and npm install -D @atmosphere-money/testing@beta.
Environment	ATM_BASE_URL, ATM_APP_DID, ATM_ENVIRONMENT=test, ATM_WEBHOOK_SECRET, and ATM_APP_SERVICE_AUDIENCE.
App dashboard	Enable only the tested modules, keep test/live separate, send a dashboard test event, and verify delivery logs.
Receiver choice	Use HTTP webhooks by default. Use XRPC receiver only if the app already hosts an XRPC service and can verify ATM service-auth plus jti replay state.
Fixtures	Use @atmosphere-money/testing for signed payment.completed, payment.refunded, subscription.updated, product.archived, tickets.issued, and ticket.checked_in fixtures.
Evidence	Record app DID, environment, payment id or hold id, delivery id, timestamp, and app order/ticket id for each acceptance step.

ATM_BASE_URL=https://checkout.atmosphere.money
ATM_APP_DID=did:plc:yourapp
ATM_ENVIRONMENT=test
ATM_WEBHOOK_SECRET=atm_whsec_test_...
ATM_APP_SERVICE_AUDIENCE=did:plc:a54sdlhmv7xklga67xamqfyq#AttestedNetwork

atmo.rsvp Tickets pilot

atmo.rsvp should treat ATM Tickets as scarce inventory and payment infrastructure. The event app owns event pages, organizer UX, ticket selection UI, scanner UI, and attendee presentation.

Register atmo.rsvp as an ATM app in test mode and enable Payments plus Tickets.
Create or reference a community calendar event URI from the event app.
Configure a ticket tier, capacity group, and optional check-in list through the app server using app service-auth and organizer assertion where available.
Read getTicketAvailability from the app server before showing ticket quantities.
Create a paid hold with buyer DID plus buyer assertion when the buyer is signed into atmo.rsvp.
Redirect to ATM checkout only after a hold succeeds; show a sold-out/try-again state on TicketHoldUnavailable.
Complete card or wallet test checkout and verify tickets.issued arrives exactly once at the app receiver.
Cancel or let a checkout expire and verify the hold releases and capacity returns.
Claim a limited free ticket with claimFreeTicket and no checkout redirect.
List buyer tickets after issuance and display the ticket in the event app.
Verify an opaque QR/pass token, check it in once, and confirm a repeat scan returns already checked in.
Refund or void a paid ticket and confirm scan authority is revoked or flagged before entry.

Tickets docs

Ticket-specific availability, holds, free claims, QR/pass tokens, and scanner flows.

Open external Tickets overview

ATM-side payment and dashboard boundary for ticket purchases.

Open guide Testing package

Signed ticket and payment fixtures for app receiver tests.

Open guide

plyr.fm music pilot

plyr.fm should start with the payment patterns that map cleanly to a music app: tips, digital purchases, paid downloads or listening entitlements, and optionally recurring fan support. Keep content access and music-library UX in plyr.fm; keep payment truth and app fee routing in ATM.

Register plyr.fm as an ATM app in test mode and enable Payments plus Products; enable Subscriptions only if recurring fan support is in scope.
Create a test creator/artist recipient and check getPayoutStatus before showing paid actions.
Create a one-time support checkout and fulfill only after payment.completed.
Create a digital product or paid-download checkout with an app order id in private metadata.
Grant the music entitlement after verified payment.completed and store ATM payment id beside the app order.
Refund the purchase and verify plyr.fm revokes or flags the entitlement from payment.refunded.
If subscriptions are enabled, create one active support subscription per payer/artist/app policy unless plyr.fm explicitly models tiers.
Handle subscription.updated, subscription.canceled, and payment.failed without duplicating the user-facing subscription row.
Verify dashboard app revenue, direct creator payments, and app fee attribution are understandable in ATM.
Test guest checkout only when plyr.fm can safely fulfill by email; use buyer assertions for signed-in buyers so they do not look like guests.

One-time tip	paymentType=support; no product entitlement unless plyr.fm wants a feed/support record.
Digital purchase	paymentType=shop with app order id and optional money.atmosphere.product strongRef.
Recurring support	subscription policy controlled by plyr.fm app config; ATM owns durable subscription/payment state.
Entitlement revoke	payment.refunded, payment.disputed, or subscription cancellation should trigger app-side access changes.

Required evidence

Before asking ATM for live access, the pilot app should send a compact evidence bundle rather than a long narrative.

Identity	App DID, app handle/name, test environment, and receiver URL or XRPC receiver DID service.
Checkout	One successful checkout id/payment id, one canceled/expired checkout, and one disabled-recipient screenshot or log.
Delivery	At least one successful delivery id, one duplicate-delivery/idempotency test, and one redrive test if webhooks are configured.
Refund/revoke	Refund id or disputed/voided fixture plus the app-side revocation result.
Tickets	Hold id, tickets.issued delivery id, free claim id, check-in result, repeat-scan result, and refund/void scan result.
Music	App order id, entitlement id, payment id, refund id, and subscription id if recurring support is enabled.

What should become SDK helpers

After atmo.rsvp and plyr.fm test against the same beta package, promote repeated rough edges into SDK helpers. Keep one-off app policy in the app.

If both apps hand-roll payability-disabled UI state, add a small response normalizer.
If both apps duplicate app-order metadata validation, add typed metadata extraction helpers.
If ticket apps repeat buyer assertion checks, tighten createTicketHoldBody and claimFreeTicketBody helpers.
If music/product apps repeat entitlement grant/revoke tests, add testing fixtures or examples before adding runtime SDK surface.
If webhooks/XRPC receivers repeat framework glue, add route helpers; keep lower-level signature and service-auth primitives available.
Do not add browser SDK helpers until hosted checkout embedding is explicitly designed and tested.