Docs
Payload schemas
Canonical envelopes, core event data shapes, and error response conventions for ATM integrations.
Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.
Event envelope
Every event has a stable envelope and a typed datapayload. The envelope is the part apps should use for verification, environment separation, idempotency, and routing.
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Delivery id (whd_...). Matches the Atm-Delivery-Id and Atm-Event-Id headers; use it for deduplication. |
| type | string | yes | Canonical event type, such as payment.completed. |
| createdAt | datetime | yes | ISO 8601 timestamp the envelope was built. |
| apiVersion | string | yes | Wire-format version (currently 2026-07). Matches the Atm-Api-Version header. |
| environment | test | live | yes | The app environment that produced the event. Matches the Atm-Environment header. |
| data | object | yes | Typed event-specific payload. Carries a $type lexicon ref (money.atmosphere.event.receive#...) for XRPC tooling. |
Payment completed
| Field | Type | Required | Description |
|---|---|---|---|
| paymentId | string | yes | ATM payment id. |
| amount | integer | yes | Final settled amount in minor currency units. |
| currency | string | yes | Lowercase ISO 4217 currency. |
| paymentType | string | yes | tip, subscription, shop, commission, ticket, or app-defined type. |
| recipientDid | did | yes | Creator, organizer, or app receiving the payment. |
| payerDid | did | no | Present when the payer was signed in or asserted. |
| listing | strongRef | no | Public catalog or listing ref when available. |
| appOrderId | string | no | Private app order id supplied in checkout metadata. |
json
{
"paymentId": "pay_...",
"amount": 2500,
"currency": "usd",
"paymentType": "shop",
"recipientDid": "did:plc:creator",
"payerDid": "did:plc:buyer",
"listing": { "uri": "at://...", "cid": "bafy..." },
"appOrderId": "ord_123"
}Subscription updated
| Field | Type | Required | Description |
|---|---|---|---|
| subscriptionId | string | yes | ATM subscription id. |
| status | string | yes | active, past_due, canceled, incomplete, or processor-specific mapped state. |
| amount | integer | yes | Current recurring amount. |
| previousAmount | integer | no | Previous amount when this event represents an amount change. |
| currency | string | yes | Lowercase ISO 4217 currency. |
| payerDid | did | no | Signed-in or asserted payer DID. |
| recipientDid | did | yes | Recipient DID. |
Catalog archived
| Field | Type | Required | Description |
|---|---|---|---|
| product.uri | at-uri | yes | Archived ATM product record URI. |
| product.cid | cid | no | CID of the archived product record when available. |
| creatorDid | did | no | Creator that owns the product. |
| appLink | object | no | Sanitized app link context, if registered. |
Ticket issued
| Field | Type | Required | Description |
|---|---|---|---|
| eventUri | at-uri | yes | Community event record URI. |
| holdId | string | no | Ticket hold that produced the issued tickets. |
| paymentId | string | no | ATM payment id for paid tickets. |
| issuedCount | integer | yes | Number of tickets issued. |
| buyerDid | did | no | Verified buyer DID when present. |
| appOrderId | string | no | Private app order id when supplied. |
Error response
XRPC and API errors should be readable by humans and stable enough for apps to branch on error codes.
json
{
"error": "RecipientNotPayable",
"message": "This recipient has not finished payment setup."
}