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 | Stable ATM event id. |
| deliveryId | string | yes | Unique delivery attempt id used for deduplication. |
| environment | test | live | yes | The app environment that produced the event. |
| type | string | yes | Canonical event type, such as payment.completed. |
| appDid | did | yes | The app receiving this event. |
| createdAt | datetime | yes | ISO timestamp for event creation. |
| data | object | yes | Typed event-specific payload. |
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 |
|---|---|---|---|
| productUri | at-uri | yes | Archived ATM product record URI. |
| productCid | cid | no | CID of the archived product record when available. |
| archivedAt | datetime | yes | Archive timestamp. |
| appProductRef | string | no | Private app fulfillment ref, 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."
}