Docs

Troubleshooting

Common integration failures and how app developers should recover from them.

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

Recipient not payable

Symptom: Checkout fails with RecipientNotPayable or PaymentSetupIncomplete.
Likely cause: The creator, organizer, or project has not completed payment setup in ATM.
Fix: Call payout status before showing purchase buttons and show a disabled state until the recipient is payable.

Invalid service-auth

Symptom: XRPC calls return AppUnauthorized, InvalidAudience, InvalidMethod, or token replay errors.
Likely cause: The service-auth JWT does not match the exact ATM audience, lxm, issuer, expiry, or jti expectations.
Fix: Mint a fresh service-auth JWT per request with iss = app DID, aud = ATM service audience, lxm = exact method NSID, short expiry, and unique jti.

Checkout expired

Symptom: The browser returns to the app but status is expired, canceled, or still processing.
Likely cause: Checkout sessions and ticket holds are time-bounded, and browser redirects can race with processor webhooks.
Fix: Poll payment status after browser return and rely on payment.completed webhook or receiver events for fulfillment.

Webhook signature mismatch

Symptom: Webhook verification fails even though the event came from ATM.
Likely cause: The handler parsed or transformed the body before verification, used the wrong environment secret, or checked an old rotated secret.
Fix: Verify against the raw request body and the signing secret for the event environment. Keep old secrets only for the documented rotation window.

Duplicate delivery

Symptom: The same event is delivered more than once.
Likely cause: ATM webhooks are at-least-once and redriveable by design.
Fix: Store delivery ids and payment/order ids before side effects. Duplicate deliveries should return success after confirming the side effect already happened.

Ticket hold unavailable

Symptom: Ticket checkout fails because a tier is sold out or a hold cannot be created.
Likely cause: Capacity changed between page render and hold creation, or another app claimed the remaining inventory.
Fix: Always call createTicketHold before checkout and update UI from the authoritative availability response.

Buyer assertion stale

Symptom: A buyer is shown as a guest or assertion verification fails.
Likely cause: The app passed only a buyerDid hint, used an expired assertion, or reused a buyer assertion JWT.
Fix: Mint a fresh buyer service-auth assertion for the action. ATM stores only verification metadata, not the raw JWT.

Troubleshooting - Atmosphere Money Docs