Operate ticketing safely.

Testing

Apps should test against the ATM app sandbox before live ticket sales. Multiple apps can test concurrently because app config, webhooks, modules, and fee settings are environment scoped.

Create types and capacity for a test event.
Confirm availability before checkout controls appear.
Create concurrent holds and verify no oversell.
Complete a paid ticket checkout through ATM test mode.
Claim a limited free ticket without checkout.
Verify and check in a ticket exactly once.
Refund or void and confirm the pass token no longer admits entry.

Sandbox walkthrough

Run this loop before a ticketing app asks for live access. The app dashboard should show the same environment, delivery ids, and event states that the starter logs locally.

Enable Tickets in the app test environment and configure a test receiver.
Create authorized ticketed-event config, types, optional type/event caps, private forms, and check-in lists.
Confirm organizer approval gates availability, holds, and free claims.
Download the public starter, copy .env.example to .env and run npm run dev; confirm GET /health. Replace the fixture auth/state adapters before real test calls, following the build guide.
Read availability and verify the dashboard/event app agree on capacity.
Create a paid hold and confirm the hold appears as reserved inventory.
Complete or cancel checkout and confirm issued tickets or released hold state.
Claim a limited free ticket and confirm capacity decrements without checkout.
Send a dashboard test event, fail it once, fix the receiver, and redrive.
Check in an opaque scan token through scan.atmosphere.tickets and confirm a second scan returns existing state.

Pilot acceptance

Use this checklist for the first event app pilot before requesting live ticket sales. The app owns event pages and organizer UX; ATM Tickets owns scarce ticket truth; ATM checkout owns payment state.

Area	Required evidence
App setup	App DID, test environment, Payments and Tickets enabled, receiver URL or XRPC receiver config, and webhook signing secret stored server-side.
Organizer setup	Organizer payout status checked before paid controls appear; ticket type, event/type capacity, and check-in list configured with organizer authority.
Availability	Event page reads authoritative availability before showing quantity controls and refreshes after hold conflicts.
Paid hold	Hold id, event URI, type id, quantity, buyer DID/assertion when signed in, checkout URL, and hold expiry captured in app logs.
Checkout	Successful payment issues tickets once; ATM-reconciled cancellation or expiry releases capacity.
Free limited claim	claimFreeTicket issues a scarce free ticket without checkout and requires a verified buyer assertion and delivery email for every fresh claim.
Callbacks	tickets.issued, ticket.refunded or ticket.voided, and ticket.checked-in are verified, deduplicated, and visible in receiver logs.
Scanner	Opaque QR/pass token verifies, checks in once, repeat scan returns already checked in, and refunded/voided ticket cannot admit entry.
Dashboard	ATM shows ticket purchase payment rows, app event delivery status, and enough ids for support without exposing buyer PII or raw scan tokens.

Send a compact evidence bundle.

Include app DID, environment, event URI, hold id, payment id, delivery id, issued ticket id, check-in result, and refund/void result. Do not send raw QR secrets, buyer emails, attendee answers, or processor ids unless support explicitly asks for a private support channel.

Open ATM pilot playbooks

Launch checklist

App is registered in ATM and Tickets is enabled in test mode.
Organizer payout setup is checked before paid ticket controls appear.
Availability reads happen before rendering buy buttons.
Concurrent hold tests cannot oversell a capacity pool.
Paid checkout issues tickets exactly once after payment succeeds.
Fresh free claims require buyer assertion, private delivery email and current item arrays; authenticated free release is tested.
QR/pass payloads contain only opaque scan tokens or scan URLs.
Scanner flows handle repeat check-in without double entry.
Refund and void events revoke or flag issued tickets.
Webhook/XRPC receiver handlers deduplicate delivery ids.

Testing cookbook

Create a test event and types with type/event capacity caps.
Run 20 concurrent holds against 10 capacity and verify exactly 10 succeed.
Complete a paid checkout and confirm issuance once and safe at-least-once callback handling.
Claim a limited free ticket with buyer assertion and no checkout redirect.
Refund or void a ticket and confirm the pass token no longer admits entry.
Scan a ticket twice and confirm the second scan returns existing check-in state.
Fail a webhook delivery, fix the endpoint, and redrive it from ATM.

Agent readiness

Use this checklist before handing the docs to an app developer or coding agent. It keeps the integration focused on safe developer actions and prevents agents from confusing ticket presentation with ticket truth.

Install @atmosphere-money/app-node and keep ticket calls on a trusted backend.
Set test ATM endpoint, app DID, service-auth audience, webhook secret, and receiver URL.
Run availability, paid hold, free claim, callback verification, and scan-token check-in fixtures.
Verify receiver idempotency with duplicate Atm-Delivery-Id or XRPC event ids.
Confirm app logs do not store raw scan tokens, buyer emails, service-auth JWTs, or webhook secrets.
Link the app developer to /llms.txt or /llms-full.txt when using an agent.

Troubleshooting

Sold out during checkout

Create a hold first

Never send buyers to ATM checkout until Tickets has successfully reserved capacity.

Invalid app auth

Check iss, aud, lxm, exp, jti

Mint fresh service-auth per request and use the exact ticket method NSID as lxm.

Buyer appears guest

Use buyer assertions

Pass buyerDid plus short-lived buyerAssertionJwt when the buyer is signed into the event app.

Duplicate check-in

Return existing state

Check-in must be idempotent. Repeat scans should report that the ticket was already checked in.

Webhook repeats

Deduplicate delivery ids

ATM events are at-least-once. Atomically persist delivery processing and side effects so retries remain recoverable.

Refunded ticket still scans

Void pass tokens

Refund and void events must revoke scan tokens or mark issued tickets invalid.

Docs changelog

2026-10-12

Aligned with current ATM main

Synced 30 schemas from 59432c22e, ticketType/event-capacity APIs, buyer/organizer authority, free release/email, exact callback names and payloads, scanner pilot, hosted surfaces and SDK beta.5 gaps.

Verification

Recorded source, separate readiness

Schema/page checks and starter fixtures validate this update. Deployed pilot, migration, publication and live-sales readiness remain separate release checks.

Example links

ATM docs	atmosphere.money/docs
Ticket lexicons	Public schema index with exact raw JSON URLs.
Agent summary	Compact index and full guide.
Starter app	Public download and source bundle for availability, holds, free claims, callbacks, and scanner calls.
Reference product	Hi.Events for feature inspiration, not protocol shape.

ATM boundary

Tickets is the ticketing module; ATM is the payment platform. Developers configure apps, fees, webhooks, and payment rails in ATM. Ticket purchases appear in the unified ATM payments ledger alongside other app-originated payments.

Do not build a second payment backend.

Paid ticket checkout should always flow through ATM. Tickets should create a hold, ask ATM to collect payment, then issue tickets after ATM confirms payment.

Read ATM checkout docs