docs: clarify payment-required extension guidance

[TateLyman]

Summary

• add guidance for modeling payment-required flows as A2A extensions rather than new core task states
• document the discovery metadata an extension should define: response codes, challenge location/format, retry proof location, receipt fields, and task-state timing
• call out security requirements for binding challenges, validating payment proof before paid output, avoiding sensitive metadata leaks, and exposing challenge headers for browser clients

Closes #1815.

Verification

• npx --yes markdownlint-cli docs/topics/extensions.md --config .github/linters/.markdownlint.json
• git diff --check
• uv run --with-requirements requirements-docs.txt mkdocs build --strict (fails on existing repo warnings unrelated to this change: missing sdk/python/api nav target, existing definitions/spec links, and existing specification anchors)

[gemini-code-assist]

Code Review

This pull request adds a 'Payment-Required Flows' section to the extensions documentation, outlining how agents advertise payment challenges and how clients should respond. The new content details transport-level specifications, challenge formats, and security best practices. Reviewer feedback recommends clarifying status code mappings for non-HTTP protocols like gRPC and including TASK_STATE_AUTH_REQUIRED as an example state for payment-related interruptions.

[gemini-code-assist]

Since A2A supports multiple transport bindings (including gRPC and JSON-RPC), it is recommended to clarify how payment challenges should be represented in non-HTTP protocols. When defining gRPC status codes for payment requirements, ensure they align with canonical mappings to maintain compatibility with gRPC transcoding systems, even if a more specific HTTP status code is available.

Suggested change

	- Which transport-level status codes can carry a payment challenge (for example,
	HTTP `402 Payment Required`)
	- Which transport-level status codes can carry a payment challenge (for example,
	HTTP 402 Payment Required or the corresponding canonical gRPC status code)

References

1. When mapping gRPC statuses to HTTP statuses, prioritize compatibility with gRPC transcoding systems by using the canonical mapping, even if a more specific HTTP status code is available.

[gemini-code-assist]

Given that payment is described as similar to authentication and authorization (line 136), TASK_STATE_AUTH_REQUIRED might also be a relevant state for agents to use when a task is interrupted for payment. Including it as an example provides more flexibility for implementers.

Suggested change

	- Whether payment is checked before task creation, or after a task has already
	entered an interrupted state such as `TASK_STATE_INPUT_REQUIRED`
	- Whether payment is checked before task creation, or after a task has already
	entered an interrupted state such as TASK_STATE_INPUT_REQUIRED or TASK_STATE_AUTH_REQUIRED

[Tehsmash]

Hi @TateLyman, thanks for the PR, we discussed this a bit in TSC meeting yesterday.

The current proposal feels a little bit like we're laying down specific rules for a sub-set of extensions which defeats the point of the flexibility of extensions.

We should consider making the proposal here an extension covering the discovery of the payment process implementing the rules and fields you've laid out. This can then be extended by other extensions implementing the specific payment flows with their specific details. This makes the payment process composable.

I would also explore other extensions like AP2 which is itself a wrapper around other payment protocols like x402.

[TateLyman]

Thanks, that direction makes sense. I rebased and adjusted the PR so the section is now framed as payment process discovery rather than core payment rules.\n\nMain changes:\n\n- renamed the section from payment-required flows to payment process discovery\n- removed the implication that A2A core should define payment-specific behavior\n- described the extension as a composable discovery layer that can point to AP2, x402, invoice-based flows, or other payment-specific extensions\n- kept the concrete x402 example as an example only, using Agent Card params for challenge/retry/receipt discovery\n\nThat should leave the actual payment flow semantics to protocol-specific extensions while preserving the buyer/client discovery problem this PR was trying to address.