@@ -34,20 +34,46 @@ class AgentcardCheckoutAuthorization(BaseModel):
     amount: Optional[str] = None
     """Display amount shown on the approval screen."""
 
-    amount_authority: Optional[Literal["display_only", "stripe_payment_intent"]] = None
+    amount_authority: Optional[Literal["processor", "agent", "page", "none", "display_only"]] = None
+    """Source of the approved amount.
+
+    `processor` is read from the processor request or payment; `agent` is the item's
+    declared amount; `page` is the checkout page total; `none` means no amount was
+    named. `display_only` appears only on authorizations recovered without a
+    provider read. `agent` and `display_only` don't prove what the processor
+    charged.
+    """
 
     amount_verified: Optional[bool] = None
+    """Whether the processor charged the approved amount.
+
+    Absent when there was no charge to compare, including tokenization checkouts.
+    """
 
     approval_url: Optional[str] = None
 
     browser_id: Optional[str] = None
     """Browser session that submitted the checkout."""
 
     charged_amount_cents: Optional[int] = None
+    """Amount the processor reported collecting.
+
+    Absent when the provider didn't observe a charge.
+    """
 
     charged_currency: Optional[str] = None
+    """Currency of `charged_amount_cents`.
+
+    Absent when the provider didn't observe a charge.
+    """
 
     charged_kind: Optional[Literal["captured", "authorized", "none"]] = None
+    """What the processor collected.
+
+    `none` means the checkout produced a token or payment method that the merchant
+    charges later. Absent when the provider reported nothing, which is common for
+    tokenization checkouts; use item events and the merchant's order record instead.
+    """
 
     expected_cents: Optional[int] = None