x402/examples/python/servers/payment-identifier
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
..

Payment-Identifier Extension Server Example

Example server demonstrating how to implement the payment-identifier extension for idempotent payment processing.

How It Works

  1. Server advertises payment-identifier extension support in PaymentRequired responses
  2. Server extracts payment ID from incoming PaymentPayload using extract_payment_identifier()
  3. After settlement, server caches the response keyed by payment ID
  4. Duplicate requests with the same payment ID return cached response without payment processing
from x402.extensions.payment_identifier import (
    PAYMENT_IDENTIFIER,
    declare_payment_identifier_extension,
    extract_payment_identifier,
)
from x402.server import x402ResourceServer

server = x402ResourceServer(facilitator)

# Advertise extension support in route config
routes = {
    "GET /weather": RouteConfig(
        accepts=[...],
        extensions={
            PAYMENT_IDENTIFIER: declare_payment_identifier_extension(required=False),
        },
    ),
}

# Cache response after settlement
async def after_settle(ctx):
    payment_id = extract_payment_identifier(ctx.payment_payload)
    if payment_id:
        idempotency_cache[payment_id] = cached_response

server.on_after_settle(after_settle)

Prerequisites

  • Python 3.10+
  • uv (install via docs.astral.sh/uv)
  • Valid EVM address for receiving payments (Base Sepolia)

Setup

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

Required environment variable:

  • EVM_ADDRESS - Ethereum address to receive payments
  1. Run the server:
uv run python main.py

Expected Output

Payment-Identifier Example Server
   Listening at http://localhost:4022

Idempotency Configuration:
   - Cache TTL: 1 hour
   - Payment ID: optional (required: false)

How it works:
   1. Client sends payment with a unique payment ID
   2. Server caches the response keyed by payment ID
   3. If same payment ID is seen within 1 hour, cached response is returned
   4. No duplicate payment processing occurs

When requests come in:

[Idempotency] Checking payment ID: pay_7d5d747be160e280504c099d984bcfe0
[Idempotency] Cache MISS - proceeding with payment
[Idempotency] Caching response for payment ID: pay_7d5d747be160e280504c099d984bcfe0

[Idempotency] Checking payment ID: pay_7d5d747be160e280504c099d984bcfe0
[Idempotency] Cache HIT - returning cached response (age: 2s)

Testing with the Client

Run the payment-identifier client example in another terminal:

cd ../../clients/payment-identifier
uv run python main.py

Extension Configuration

Optional Payment ID (Default)

extensions={
    PAYMENT_IDENTIFIER: declare_payment_identifier_extension(required=False),
}

Clients may optionally provide a payment ID. If provided, it enables idempotency.

Required Payment ID

extensions={
    PAYMENT_IDENTIFIER: declare_payment_identifier_extension(required=True),
}

Clients must provide a payment ID. Requests without one will be rejected.

Production Considerations

  1. Use a distributed cache (Redis, Memcached) instead of in-memory dict
  2. Configure appropriate TTL based on your use case
  3. Consider cache key structure to include route/method for multi-endpoint servers
  4. Monitor cache hit rates to optimize performance