From 879d56f3b18ed072661d8c4b273abb171eb1b4fa Mon Sep 17 00:00:00 2001 From: hiroTamada <88675973+hiroTamada@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:00:36 +0000 Subject: [PATCH 1/2] Document AgentCard amount authority, charge fields, and checkout item events --- integrations/wallets/agentcard.mdx | 51 +++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/integrations/wallets/agentcard.mdx b/integrations/wallets/agentcard.mdx index 9901b786..548c3cbc 100644 --- a/integrations/wallets/agentcard.mdx +++ b/integrations/wallets/agentcard.mdx @@ -788,13 +788,47 @@ 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 KERNEL 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` marks an authorization recovered without a provider read | +| `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 KERNEL 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 what happened to the held request and, for +stripe, the payment that follows it: + +| event | meaning | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `checkout_response_replayed` | KERNEL 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` | KERNEL couldn't classify the response. treat the attempt as indeterminate and don't retry | + +payment events are recorded when the checkout page confirms a stripe payment +intent, checkout session, or payment method that uses the replayed token. other +processors only record `checkout_response_replayed`. 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 +838,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 From 5614a6effeef829b2828282699a2f6d076c1d317 Mon Sep 17 00:00:00 2001 From: hiroTamada <88675973+hiroTamada@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:57:27 +0000 Subject: [PATCH 2/2] Correct which AgentCard checkout events each processor records --- integrations/wallets/agentcard.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/integrations/wallets/agentcard.mdx b/integrations/wallets/agentcard.mdx index 548c3cbc..5af67eda 100644 --- a/integrations/wallets/agentcard.mdx +++ b/integrations/wallets/agentcard.mdx @@ -790,7 +790,7 @@ terminal and never pass its output to an agent. | 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` marks an authorization recovered without a provider read | +| `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; KERNEL 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 | @@ -808,8 +808,10 @@ for that result. ### Checkout item events -the card's item events record what happened to the held request and, for -stripe, the payment that follows it: +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 | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | @@ -820,9 +822,12 @@ stripe, the payment that follows it: | `credential_tokenized` | the processor accepted the card as a token; this isn't a charge | | `payment_unknown` | KERNEL couldn't classify the response. treat the attempt as indeterminate and don't retry | -payment events are recorded when the checkout page confirms a stripe payment -intent, checkout session, or payment method that uses the replayed token. other -processors only record `checkout_response_replayed`. event `data` can include: +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`