docs: fix Python x402 header and API inconsistencies

[aaitor]

Summary

This PR fixes all Python code examples in the documentation to be consistent with the API reference and x402 v2 specification.

Issues Fixed

1. ✅ Uppercase Header Names

Changed all instances of uppercase PAYMENT-SIGNATURE and Payment-Signature to lowercase payment-signature (required by x402 v2 HTTP transport spec).

2. ✅ Authorization Header Usage

Replaced old Authorization: Bearer <token> format with the new payment-signature header format.

3. ✅ Deprecated API Methods

Replaced deprecated payments.requests.isValidRequest() / is_valid_request() with the proper x402 v2 facilitator API:

• payments.facilitator.verify_permissions()
• payments.facilitator.settle_permissions()
• build_payment_required() helper

Files Changed

• docs/development-guide/process-requests.mdx - Fixed headers and removed Bearer token logic
• docs/development-guide/query-agents.mdx - Fixed 9 header instances and streaming example
• docs/getting-started/quickstart.mdx - Fixed header case
• docs/integrate/patterns/charge-credits.mdx - Updated to show proper verify/settle flow
• docs/integrate/patterns/validate-requests.mdx - Rewritten to use correct x402 v2 API
• docs/integrate/quickstart/python.mdx - Fixed header case
• docs/integrations/google-a2a.mdx - Fixed header reference
• docs/integrations/mcp.mdx - Fixed header case

Before vs After

Before (❌ Incorrect):

auth_header = request.headers.get("Authorization")
x402_token = auth_header.replace("Bearer ", "") if auth_header else ""
result = payments.requests.is_valid_request(token, body)

After (✅ Correct):

from payments_py.x402.helpers import build_payment_required

x402_token = request.headers.get("payment-signature", "")

payment_required = build_payment_required(
    plan_id=plan_id,
    endpoint=endpoint,
    agent_id=agent_id,
    http_verb=http_verb
)

verification = payments.facilitator.verify_permissions(
    payment_required=payment_required,
    x402_access_token=x402_token,
    max_amount="1"
)

Testing

• ✅ All Python code examples now match the API reference patterns in /docs/api-reference/python/
• ✅ Headers use lowercase payment-signature per x402 v2 spec
• ✅ No deprecated API methods remain in critical user-facing examples

Related

• x402 v2 HTTP transport spec: https://github.com/coinbase/x402/blob/main/specs/transports-v2/http.md
• Source of truth: /docs/api-reference/python/ directory

🤖 Generated with Claude Code