Concepts
How do receipts work?
High-value mutations return HMAC-signed receipts. Agents keep them as proof of transactions.
When are receipts issued?
| Event | Receipt kind |
|---|---|
| Booking confirmed | booking_confirmed |
| Booking cancelled | booking_cancelled |
| Refund issued | refund_issued |
Receipt structure
{
"receipt": {
"kind": "booking_confirmed",
"subject": "b_123",
"issued_at": "2026-05-01T12:00:00Z",
"issuer": "commerce-api",
"signature": "hmac-sha256:a1b2c3d4..."
}
}Verifying receipts
POST /v1/receipts/verify
Content-Type: application/json
{ "kind": "booking_confirmed", "subject": "b_123", "issued_at": "...", "issuer": "commerce-api", "signature": "..." }Returns 200 OK if valid. Agents with the shared key can also verify locally using the canonical form.