Atmosphere Tickets Docs

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 tiers 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 app-scoped ticketed-event config, tier, capacity group, tier form, and check-in list.
Confirm organizer approval gates availability, holds, and free claims.
Run examples/tickets-node-app and confirm GET /health.
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 tier, capacity group, and check-in list created from app server.
Availability	Event page reads authoritative availability before showing quantity controls and refreshes after hold conflicts.
Paid hold	Hold id, event URI, tier id, quantity, buyer DID/assertion when signed in, checkout URL, and hold expiry captured in app logs.
Checkout	Successful payment issues tickets once; canceled or expired checkout releases capacity.
Free limited claim	claimFreeTicket issues a scarce free ticket without checkout and requires buyer assertion for signed-in buyers.
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 group.
Paid checkout issues tickets exactly once after payment succeeds.
Limited free ticket claims require a buyer assertion.
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, ticket tier, and capacity group.
Run 20 concurrent holds against 10 capacity and verify exactly 10 succeed.
Complete a paid checkout and confirm tickets.issued is delivered once.
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. Store delivery ids before performing side effects.

Refunded ticket still scans

Void pass tokens

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

Docs changelog

2026-06 beta

Developer docs expanded

Added app onboarding, auth model, receiver options, generated XRPC reference, testing cookbook, and lexicon review package.

Link to published example repos and generated API reference artifacts after the review repos are public.

Example links

ATM docs	atmosphere.money/docs
Local ATM example	`examples/atm-node-app` in the ATM repo.
Ticket lexicons	`lexicons/tickets/atmosphere` in this repo.
Agent summary	`/llms.txt` and `/llms-full.txt` on atmosphere.tickets.
Starter app	`examples/tickets-node-app` in this repo 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

Operate ticketing safely.