Universal Commerce Protocol (UCP) integration for Shopware 6.

This plugin is a reference implementation of the UCP protocol for Shopware 6. For most payment methods there is still work to do before production use:

• PaymentHandlerService — Exposes payment handlers in the discovery profile (e.g. /.well-known/ucp). Currently returns a single default “business tokenizer” handler; mapping of Shopware payment methods to UCP handlers (e.g. Google Pay) is reserved for future use and not fully implemented.
• PaymentProcessingService — Applies UCP payment data to the cart and maps handler IDs to Shopware payment methods. The current implementation is a placeholder: it picks the first available payment method instead of resolving handler IDs from configuration, and payment credentials are stored on the cart for later processing rather than being fully integrated with order creation.

If you integrate additional payment methods or processors, extend these services and wire them to your Shopware payment method configuration and order flow.

1. Install via Composer (VCS) from your Shopware root:

   composer config repositories.swagucp vcs https://github.com/agentic-commerce-lab/SwagUcp.git
   composer require shopware/ucp-integration:dev-main

2. Install and activate the plugin:

   bin/console plugin:refresh
   bin/console plugin:install --activate SwagUcp

3. Clear cache:

   bin/console cache:clear

Configure the plugin in Shopware Admin:

• Extensions → My extension → UCP Integration → configure

⚠️ No hardcoded keys! Each installation generates unique cryptographic keys.

You don't need to do anything! When the plugin is first accessed:

1. The plugin checks if signing keys exist in the configuration
2. If no keys are found, it automatically generates:
   • A random Key ID: shopware_ucp_<16-char-hex>
   • An EC P-256 key pair using PHP's OpenSSL extension
3. Keys are stored in Shopware's SystemConfig (database) and persist permanently

To trigger key generation, simply access https://your-shop.com/.well-known/ucp after installation.

If you prefer to generate your own keys (e.g., for key rotation or compliance requirements):

# Generate EC P-256 private key
openssl ecparam -genkey -name prime256v1 -noout -out private.pem

# Extract public key
openssl ec -in private.pem -pubout -out public.pem

# View the keys
cat private.pem  # Copy to "Signing Private Key" field
cat public.pem   # Copy to "Signing Public Key" field

Then in Shopware Admin:

1. Go to Settings → System → Plugins → SwagUcp
2. Paste the private key into Signing Private Key (PEM)
3. Paste the public key into Signing Public Key (PEM)
4. Set a unique Signing Key ID (e.g., myshop_2026_01)
5. Save and clear cache

To rotate keys without downtime:

1. Generate new keys using the commands above
2. Update the configuration with new keys and a new Key ID
3. The new public key will immediately be published at /.well-known/ucp
4. Platforms will fetch the new key on their next request

Check that your keys are published correctly:

curl https://your-shop.com/.well-known/ucp | jq '.signing_keys'

Expected output:

[
  {
    "kid": "shopware_ucp_abc123...",
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "...",
    "use": "sig",
    "alg": "ES256"
  }
]

The plugin provides multiple layers of security:

Enable "Agent Whitelist" and configure allowed domains:

api.openai.com
generativelanguage.googleapis.com
api.anthropic.com
api.cohere.ai

Agents must send a UCP-Agent header with their profile URL:

UCP-Agent: UCP/2026-01-11 profile="https://api.openai.com/.well-known/ucp"

The plugin extracts the domain and checks against the whitelist.

Enable "Require Agent Signature" for cryptographic verification:

1. Agent signs the request body with their private key
2. Sends signature in Request-Signature header (Detached JWS)
3. Plugin fetches agent's public keys from their /.well-known/ucp
4. Verifies the signature matches the request body

This ensures:

• ✅ Only authorized agents can call the endpoints
• ✅ Requests cannot be tampered with
• ✅ Non-repudiation (agent cannot deny sending request)

If whitelist is enabled but no domains configured, these are automatically allowed:

Agent Whitelist: ❌ Disabled
Require Signature: ❌ Disabled

Agent Whitelist: ✅ Enabled
Whitelisted Domains: api.openai.com, api.anthropic.com
Require Signature: ❌ Disabled

Agent Whitelist: ✅ Enabled
Whitelisted Domains: api.openai.com
Require Signature: ✅ Enabled

• UCP profile available at /.well-known/ucp
• Automatic capability negotiation
• Payment handler discovery
• JWK signing keys published for webhook verification

• POST /ucp/checkout-sessions - Create checkout
• GET /ucp/checkout-sessions/{id} - Get checkout
• PUT /ucp/checkout-sessions/{id} - Update checkout
• POST /ucp/checkout-sessions/{id}/complete - Complete checkout
• POST /ucp/checkout-sessions/{id}/cancel - Cancel checkout

Outgoing webhooks (order updates) are signed using Request-Signature header:

Request-Signature: eyJhbGciOiJFUzI1NiIsImtpZCI6InNob3B3YXJlX3VjcF8yMDI2In0..MEUCIQDx...

Platforms can verify using the public key from /.well-known/ucp.

vendor/bin/phpunit tests/Unit --testdox

vendor/bin/phpunit tests/Integration --testdox

./tests/run_live_flow_test.sh

See tests/README.md for detailed test documentation.

curl https://your-shop.com/.well-known/ucp

curl -X POST https://your-shop.com/ucp/checkout-sessions \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "UCP-Agent: UCP/2026-01-11 profile=\"https://api.openai.com/.well-known/ucp\"" \
  -d '{
    "line_items": [
      {
        "item": {
          "id": "product-123",
          "title": "Test Product",
          "price": 1000
        },
        "quantity": 1
      }
    ]
  }'

curl -X POST https://your-shop.com/ucp/checkout-sessions \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "UCP-Agent: UCP/2026-01-11 profile=\"https://agent.example.com/.well-known/ucp\"" \
  -H "Request-Signature: eyJhbGciOiJFUzI1NiIsImtpZCI6ImFnZW50X2tleV8xIn0..SIGNATURE" \
  -d '{"line_items": [...]}'

Before going live:

• Enable Agent Whitelist in plugin settings
• Configure allowed agent domains (or leave empty for known platforms)
• Consider enabling "Require Agent Signature" for high-value transactions
• Verify your signing keys are generated (check /.well-known/ucp)
• Test the integration with your AI agent partner
• Ensure HTTPS is configured
• Review webhook endpoints are secured

• Add the agent's domain to the whitelist
• Or disable whitelist for development

• Agent must send valid Request-Signature header
• Public keys must be published at agent's /.well-known/ucp

• Clear Shopware cache: bin/console cache:clear
• Keys auto-generate on first request

Apache License 2.0