A. McDermott e9d9b3a5ba
feat: Payment Identifier Extension SDK - Python (#1111)
* feat(python): add payment-identifier extension types and constants

- Add PaymentIdentifierInfo and PaymentIdentifierExtension Pydantic models
- Add constants: PAYMENT_IDENTIFIER, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_PATTERN
- Define PaymentIdentifierSchema type alias

* feat(python): add payment-identifier utility functions

- Add generate_payment_id() to create UUID v4-based payment IDs
- Add is_valid_payment_id() to validate ID format (16-128 chars, alphanumeric + hyphens/underscores)

* feat(python): add payment-identifier JSON Schema definition

- Add payment_identifier_schema compliant with JSON Schema Draft 2020-12
- Schema validates required boolean and optional id string field

* feat(python): add payment-identifier validation and extraction functions

- Add ValidationResult dataclass for validation results
- Add is_payment_identifier_extension() type guard
- Add validate_payment_identifier() for full extension validation
- Add extract_payment_identifier() to extract ID from PaymentPayload
- Add extract_and_validate_payment_identifier() combined function
- Add has_payment_identifier() to check extension presence
- Add is_payment_identifier_required() to check requirement flag
- Add validate_payment_identifier_requirement() for requirement compliance

* feat(python): add payment-identifier client utilities

- Add append_payment_identifier_to_extensions() to append payment ID to extensions dict
- Only appends if server declared the extension
- Generates new ID if not provided

* feat(python): add payment-identifier resource server utilities

- Add declare_payment_identifier_extension() to create extension declaration
- Add PaymentIdentifierResourceServerExtension class implementing ResourceServerExtension protocol
- Add payment_identifier_resource_server_extension singleton instance

* feat(python): add payment-identifier extension main module

- Export all public APIs from payment-identifier extension
- Add comprehensive usage documentation with examples for servers, clients, and idempotency

* feat(python): export payment-identifier extension from extensions module

- Add payment-identifier imports and exports to main extensions __init__.py
- Export all constants, types, functions, and classes for public API

* fix(python): resolve ValidationResult type mismatch in extensions module

- Export payment_identifier.ValidationResult as ValidationResult (matches payment_identifier function return types)
- Export bazaar.ValidationResult as BazaarValidationResult for explicit bazaar usage
- Both ValidationResult classes are structurally equivalent (same dataclass fields)
- Fixes type mismatch where payment_identifier functions returned payment_identifier.ValidationResult but ValidationResult imported from x402.extensions was bazaar.ValidationResult

* refactor(python): rename payment_identifier ValidationResult to PaymentIdentifierValidationResult

- Rename ValidationResult class to PaymentIdentifierValidationResult in payment_identifier/validation.py
- Update all function return types and usages throughout validation.py
- Update exports in payment_identifier/__init__.py
- Update imports/exports in extensions/__init__.py
- Keep ValidationResult from bazaar as default export for backward compatibility
- Export PaymentIdentifierValidationResult separately for explicit payment_identifier usage
- Makes naming consistent with BazaarValidationResult pattern

* test(python): add comprehensive test suite for payment_identifier extension

- Add test_types.py: Test constants and Pydantic models
- Add test_utils.py: Test ID generation and validation functions
- Add test_validation.py: Test all validation and extraction functions
- Add test_client.py: Test client-side utilities
- Add test_server.py: Test server-side utilities
- Tests cover all major functionality including edge cases and error handling
- Follows same structure as bazaar extension tests

* fix(python): fix payment_identifier test helper and assertions

- Fix create_extension_with_id helper to handle invalid IDs for testing
- Update test assertion to check for 'identifier' in error message
- All 67 tests now passing

* fix(python): add ValidationResult alias for backward compatibility

- Add ValidationResult = BazaarValidationResult alias after bazaar import
- Fixes AttributeError when importing ValidationResult from x402.extensions
- ValidationResult was imported as BazaarValidationResult but exported in __all__
- Now both ValidationResult and BazaarValidationResult are available

* test(python): add test to verify __all__ exports are importable

- Add test_exports.py to verify all items in __all__ can be imported
- Tests that ValidationResult alias works correctly
- Tests that 'import *' works as expected
- This would have caught the ValidationResult AttributeError bug

* fix(python): make jsonschema import lazy in payment_identifier validation

- Remove module-level jsonschema import that raised ImportError
- Import jsonschema lazily only when schema validation is needed
- Return validation error instead of raising ImportError at module level
- Allows payment_identifier extension to be imported without jsonschema
- Users can still use non-validation functions without optional dependency

* fix(python): fix linting errors

- Remove unused variable in test_types.py
- Fix import sorting in extensions/__init__.py
- Add noqa comment for intentional E402 (import after alias)

* Lint

* docs(python): add payment-identifier extension examples

Add client and server examples demonstrating how to use the
payment-identifier extension for idempotent payment processing.

Client example shows:
- Generating payment IDs with generate_payment_id()
- Using on_before_payment_creation hook to inject the ID
- Making duplicate requests to demonstrate cache behavior

Server example shows:
- Declaring extension support with declare_payment_identifier_extension()
- Extracting payment IDs with extract_payment_identifier()
- Caching responses after settlement for idempotency

* Lint

* Format

* Changelog
2026-02-11 18:46:46 -05:00

3.9 KiB

Payment-Identifier Extension Client Example

Example client demonstrating how to use the payment-identifier extension to enable idempotency when making payments.

How It Works

  1. Client generates a unique payment ID using generate_payment_id()
  2. Client includes the payment ID in the PaymentPayload using append_payment_identifier_to_extensions()
  3. Server caches responses keyed by payment ID
  4. Retry requests with the same payment ID return cached responses without re-processing payment
from x402 import x402Client
from x402.extensions.payment_identifier import (
    append_payment_identifier_to_extensions,
    generate_payment_id,
)
from x402.http.clients import x402HttpxClient

client = x402Client()
# ... register schemes ...

# Generate a unique payment ID for this logical request
payment_id = generate_payment_id()

# Hook into payment flow to add the payment ID before payload creation
async def before_payment_creation(context):
    extensions = context.payment_required.extensions
    if extensions is not None:
        append_payment_identifier_to_extensions(extensions, payment_id)

client.on_before_payment_creation(before_payment_creation)

async with x402HttpxClient(client) as http:
    # First request - payment is processed
    response1 = await http.get(url)

    # Retry with same payment ID - cached response returned (no payment)
    response2 = await http.get(url)

Prerequisites

Setup

  1. Install dependencies:
uv sync
  1. Copy .env-local to .env and add your private key:
cp .env-local .env

Required environment variable:

  • EVM_PRIVATE_KEY - Ethereum private key for EVM payments
  1. Start the payment-identifier server (in another terminal):
cd ../../servers/payment-identifier
uv run python main.py
  1. Run the client:
uv run python main.py

Expected Output

Generated Payment ID: pay_7d5d747be160e280504c099d984bcfe0

====================================================
First Request (with payment ID: pay_7d5d747be160e280504c099d984bcfe0)
====================================================
Making request to: http://localhost:4022/weather

Response (1523ms): {"report": {"weather": "sunny", "temperature": 70, "cached": false}}

Payment settled on eip155:84532

====================================================
Second Request (SAME payment ID: pay_7d5d747be160e280504c099d984bcfe0)
====================================================
Making request to: http://localhost:4022/weather

Expected: Server returns cached response without payment processing

Response (45ms): {"report": {"weather": "sunny", "temperature": 70, "cached": true}}

No payment processed - response served from cache!

====================================================
Summary
====================================================
   Payment ID: pay_7d5d747be160e280504c099d984bcfe0
   First request:  1523ms (payment processed)
   Second request: 45ms (cached)
   Cached response was 97% faster!

Use Cases

  • Network failures: Safely retry failed requests without duplicate payments
  • Client crashes: Resume requests after restart using persisted payment IDs
  • Load balancing: Same request can hit different servers with shared cache
  • Testing: Replay requests during development without spending funds

Best Practices

  1. Generate payment IDs at the logical request level, not per retry
  2. Persist payment IDs for long-running operations so they survive restarts
  3. Use descriptive prefixes (e.g., order_, sub_) to identify payment types
  4. Don't reuse payment IDs across different logical requests