Implement a UCP API Bridge Module

[muratcakir]

The UCP API Bridge Module enables "Agentic Commerce" by providing a standardized interface for AI agents (like Google Gemini). It handles the discovery of shop capabilities, manages autonomous shopping sessions, and triggers the headless checkout process.

---

Conceptual Building Blocks

1. Discovery Endpoint (.well-known/ucp)

This is the "Hello World" of UCP. It tells the AI agent that this Smartstore instance is UCP-capable and where to find the API endpoints.

• Purpose: Expose a static or dynamic JSON file.
• Pseudo-Code:

GET /.well-known/ucp 
=> Return { version: "1.0", endpoints: { session_create, checkout_complete }, public_keys: [...] }

2. UCP Session Management

AI agents need "sticky" pricing and inventory data while they "think" or compare products.

• Purpose: Map an AI request to a temporary Smartstore quote or shopping cart.
• Logic:
• Validate product availability.
• Calculate real-time prices including taxes (via ITaxService).
• Freeze the price for a specific duration (e.g., 15 minutes).
• Return a session_id to the agent.

3. Headless Checkout Orchestration

The bridge between the AI agent and the IOrderProcessingService.

• Purpose: Convert the agent's final intent into a Smartstore order.
• Workflow:
• Receive session_id, shipping address, and payment_token.
• Initialize a ProcessPaymentRequest with IsUcpTransaction = true.
• Pass the token into the UcpPaymentToken property.
• Trigger PlaceOrderAsync.

4. Security & Signature Verification

To prevent fraud, every request from an AI agent must be cryptographically signed.

• Purpose: Ensure the request actually comes from a verified AI provider (e.g., Google).
• Logic: Implement an Action Filter that verifies the UCP-Signature header against the provider's public keys before any controller logic is executed.

---

Proposed Plugin Structure

Component	Responsibility
DiscoveryController	Handles the .well-known/ucp route.
SessionController	Handles session_create and session_update.
CheckoutController	Handles checkout_complete.
UcpSessionService	Manages the lifecycle of agent sessions in the DB.
SignatureRequirement	Middleware/Filter for cryptographic request validation.

---

Implementation Tasks

• Routing: Register the standardized .well-known route in the RouteProvider.
• Models: Create DTOs for UCP 1.0 (Request/Response schemas).
• Price Calculation: Integrate with Smartstore’s IPriceCalculationService to provide "Agent-Guaranteed" pricing.
• Checkout Bridge: Map UCP shipping and payment data to the enhanced ProcessPaymentRequest.
• Testing: Create a mock tool to simulate an AI agent sending signed JSON payloads.

---

Summary

The UCP Bridge Plugin doesn't replace the Smartstore checkout; it provides a second, headless door to it. It leverages the Core's new ability to process tokenized payments while maintaining all existing business rules (taxes, shipping costs, stock management).

[muratcakir]

Snippets / Blueprints / Pseudo code

ucp.json

{
  "ucp_version": "1.0",
  "capabilities": {
    "session_management": true,
    "guest_checkout": true,
    "account_linking": false
  },
  "endpoints": {
    "session_create": "https://ihr-shop.de/api/ucp/sessions/create",
    "session_update": "https://ihr-shop.de/api/ucp/sessions/update",
    "checkout": "https://ihr-shop.de/api/ucp/checkout/complete"
  },
  "verification": {
    "public_key_url": "https://ihr-shop.de/api/ucp/keys/public.pem",
    "signing_algorithm": "RS256"
  },
  "supported_payment_methods": [
    "google_pay",
    "apple_pay",
    "stripe_token"
  ]
}

The agent's query

{
  "product_id": "GTIN-123456789",
  "quantity": 1,
  "intent": "purchase_intent",
  "context": {
    "currency": "EUR",
    "locale": "de-DE",
    "shipping_destination": {
      "country_code": "DE",
      "postal_code": "44137"
    }
  }
}

Smartstore's response

{
  "session_id": "UCP-987654321",
  "expires_at": "2026-01-30T21:30:00Z",
  "line_items": [
    {
      "sku": "SM-PROD-001",
      "name": "Smartstore Premium Shirt",
      "unit_price": 49.90,
      "tax_amount": 7.97,
      "currency": "EUR"
    }
  ],
  "totals": {
    "sub_total": 41.93,
    "shipping": 4.90,
    "tax_total": 7.97,
    "grand_total": 54.80
  },
  "required_actions": ["provide_shipping_address", "select_payment_method"]
}

Actions

[HttpPost("api/ucp/sessions/create")]
public async Task<IActionResult> CreateSession([FromBody] UcpSessionRequest request)
{
    // 1. Validate the product availability in Smartstore database
    var product = await _productService.GetProductByGtinAsync(request.ProductId);
    if (product == null || product.StockQuantity <= 0)
    {
        return NotFound(new { error = "Product_Unavailable" });
    }

    // 2. Calculate price using Smartstore's internal PriceCalculationService
    var priceContext = _priceCalculationService.CreatePriceContext(product, request.Quantity);
    var calculationResult = await _priceCalculationService.CalculatePriceAsync(priceContext);

    // 3. Create a temporary UCP session (e.g., as a specialized 'ShoppingCart' or 'Quote' record)
    var session = await _ucpSessionService.InitializeSessionAsync(product, calculationResult);

    // 4. Return the standardized UCP response
    return Ok(new {
        session_id = session.Guid.ToString(),
        grand_total = calculationResult.FinalPrice
        // ... more data
    });
}

[HttpPost("api/ucp/checkout/complete")]
public async Task<IActionResult> CompleteCheckout([FromBody] UcpCheckoutRequest request)
{
    // 1. Retrieve the temporary UCP session data
    var session = await _ucpSessionService.GetSessionAsync(request.SessionId);
    if (session == null) return BadRequest("Session_Expired");

    // 2. Map UCP shipping address to Smartstore Address entity
    var shippingAddress = MapToSmartstoreAddress(request.ShippingAddress);

    // 3. Process payment via the specialized PaymentProvider
    // In UCP, we usually 'pass-through' the token to the gateway
    var paymentResult = await _paymentService.ProcessUcpPaymentAsync(request.Payment);

    if (paymentResult.Success)
    {
        // 4. Use Smartstore's internal service to place the final order
        var placementResult = await _orderPlacementService.PlaceOrderAsync(session.Cart, shippingAddress, paymentResult);

        return Ok(new {
            order_id = placementResult.PlacedOrder.OrderNumber,
            status = "Success",
            confirmation_url = Url.RouteUrl("OrderDetails", new { id = placementResult.PlacedOrder.Id }, Request.Scheme)
        });
    }

    return BadRequest(new { error = "Payment_Failed" });
}

IUcpSessionService

    public interface IUcpSessionService
    {
        // Creates a new temporary session for an AI agent
        Task<UcpSession> CreateSessionAsync(Product product, int quantity, decimal totalAmount);

        // Retrieves an existing session by its unique ID
        Task<UcpSession> GetSessionByGuidAsync(string sessionGuid);

        // Updates the session (e.g., when the agent adds shipping info)
        Task UpdateSessionAsync(UcpSession session);

        // Marks the session as "converted" once the order is placed
        Task CompleteSessionAsync(int sessionId, int orderId);
        
        // Cleans up expired sessions from the database
        Task DeleteExpiredSessionsAsync();
    }

UcpSession

public class UcpSession : BaseEntity
{
    // Unique identifier sent to the AI agent
    public string SessionGuid { get; set; }

    // Reference to the Smartstore product
    public int ProductId { get; set; }
    public int Quantity { get; set; }

    // Locked price to prevent changes during the agent's decision process
    public decimal LockedTotalAmount { get; set; }
    public string CurrencyCode { get; set; }

    // Metadata about the agent (e.g., "Google-Gemini-1.0")
    public string AgentIdentifier { get; set; }

    public DateTime ExpiryDateUtc { get; set; }
    public bool IsCompleted { get; set; }
    public int? OrderId { get; set; } // Link to the final Smartstore order
}

UcpPaymentResult

    public class UcpPaymentResult
    {
        // Indicates if the transaction was successfully authorized
        public bool Success { get; set; }

        // The unique transaction ID from the provider (e.g., Stripe Pi_...)
        public string TransactionId { get; set; }

        // A machine-readable error code for the AI agent
        public UcpPaymentErrorCode? ErrorCode { get; set; }

        // A localized message that the AI agent can read to the user
        public string ErrorMessage { get; set; }

        // Optional: Data needed for 3DSecure if the agent supports SCA (Strong Customer Authentication)
        public string ActionRequiredUrl { get; set; }
    }

    public enum UcpPaymentErrorCode
    {
        None = 0,
        InvalidToken = 10,       // Token is malformed or expired
        InsufficientFunds = 20,  // Card declined
        AuthenticationRequired = 30, // Needs 3DS / SCA
        ProviderDown = 40,       // Gateway is unreachable
        AmountMismatch = 50      // Requested amount differs from session
    }