Document AgentCard amount authority, charge fields, and checkout events (#759)

* Document AgentCard amount authority, charge fields, and checkout item events

* Correct which AgentCard checkout events each processor records

Author: hiroTamada

integrations/wallets/agentcard.mdx

@@ -788,13 +788,52 @@ continue observing an existing checkout; don't use it as evidence that a
 payment succeeded or failed. run `--open` only in a trusted, human-operated
 terminal and never pass its output to an agent.
 
-| field                              | interpretation                                                                                       |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `amount_authority: 'display_only'` | the request does not prove a charge amount; tokenization requests can have this value                |
-| `amount_verified`                  | whether the observed amount matched the approved amount when verification was available              |
-| `charged_kind`                     | `captured`, `authorized`, or `none` as reported by the provider path                                 |
-| `replay_attempted`                 | whether <span className="kernel-brand-name">KERNEL</span> attempted to replay the processor response |
-| `replay_delivered`                 | whether that response reached the browser; this does not confirm a merchant order                    |
+| field              | interpretation                                                                                                                                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `amount_authority` | where the approved amount came from: `processor` (the processor request or payment), `agent` (the item's declared `amount`), `page` (the checkout page total), or `none`. `display_only` is a legacy provider value; <span className="kernel-brand-name">KERNEL</span> also sets it when recovering an authorization before the provider reports an authority |
+| `amount_verified`  | whether the processor charged the approved amount. absent when there was no charge to compare                                                                                                                                  |
+| `charged_amount_cents`, `charged_currency` | what the processor reported collecting. absent when agentcard didn't observe a charge                                                                                                               |
+| `charged_kind`     | `captured`, `authorized`, or `none` (the checkout returned a token the merchant charges later). absent when agentcard reported nothing                                                                                         |
+| `replay_attempted` | whether <span className="kernel-brand-name">KERNEL</span> attempted to replay the processor response                                                                                                                           |
+| `replay_delivered` | whether that response reached the browser; this does not confirm a merchant order                                                                                                                                              |
+
+`amount_authority: 'agent'` and `'display_only'` only restate the amount you
+declared on the item; they don't prove what the processor charged. when the
+held request is a tokenization request, such as a stripe card token or payment
+method, agentcard returns the token to the page and never sees the charge. these
+checkouts usually report `amount_authority: 'agent'` with no `amount_verified`
+or `charged_*` fields, even when the payment succeeds. the merchant page charges
+the token in a later request; use item events and the merchant's order record
+for that result.
+
+### Checkout item events
+
+the card's item events record the processor's response to the held request and,
+for stripe, the payment that follows it. this table lists only these processor
+events; the item also records `checkout_authorization_*` and
+`checkout_preparation_*` lifecycle events:
+
+| event                                                                                  | meaning                                                                                                                                       |
+| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checkout_response_replayed`                                                           | <span className="kernel-brand-name">KERNEL</span> replayed the approved processor response to the browser. `data.status` is its HTTP status   |
+| `payment_succeeded`                                                                    | the processor reported the follow-up payment succeeded                                                                                        |
+| `payment_requires_action`, `payment_processing`                                        | the payment needs customer action, such as 3D Secure, or is still processing                                                                   |
+| `payment_declined`, `payment_failed`, `credential_rejected`                            | the processor refused the payment or the card                                                                                                 |
+| `credential_tokenized`                                                                 | the processor accepted the card as a token; this isn't a charge                                                                               |
+| `payment_unknown`                                                                      | <span className="kernel-brand-name">KERNEL</span> couldn't classify the response. treat the attempt as indeterminate and don't retry           |
+
+every processor records an event for the held request's response, such as
+`credential_tokenized` or `payment_unknown`, alongside `checkout_response_replayed`.
+for stripe, payment events are also recorded when the checkout page confirms a
+payment intent, checkout session, or payment method that uses the replayed
+token. for other processors, events cover only the held request's response; the
+follow-up payment isn't observed. event `data` can include:
+
+- `processor` and `request_kind`, such as `checkout_confirm` or `payment_intent_confirm`
+- `provider_status`, the stripe payment intent status, such as `succeeded`
+- `provider_payment_status`, the stripe checkout session payment status, such as `paid`
+- `provider_error_code` and `provider_decline_code` on refusals
+- `provider_http_status`, and stripe ids such as `payment_intent_id` and `checkout_session_id`
 
 declines, expirations, and provider failures can return a processor-shaped
 failure response to the browser. the exact response depends on the native
@@ -804,7 +843,8 @@ doesn't prove that the purchase succeeded or failed.
 your reconciliation policy must return `succeeded` only when the merchant order
 record confirms a paid order whose merchant, items, amount, and currency match
 the frozen purchase object. treat `state.authorization`, `charged_kind`,
-`replay_delivered`, item events, and the checkout page as supporting evidence.
+`replay_delivered`, item events such as `payment_succeeded`, and the checkout
+page as supporting evidence.
 merchant success text is page-specific: **Thanks for your payment** can appear
 for one stripe checkout, but no generic success-text matcher proves that the
 merchant created the expected order. return `indeterminate` when the sources