Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview
On this page

WooCommerce plugin

The Sarvex UCP WooCommerce plugin integrates your WooCommerce store with Sarvex's Google UCP checkout platform. It handles:

Generated from plugin/woocommerce/README.md in the Sarvex repository — edit the source there, not this page.

The Sarvex UCP WooCommerce plugin integrates your WooCommerce store with Sarvex’s Google UCP checkout platform. It handles:

  1. Signal Sending — Notifies Sarvex when products, prices, or inventory change
  2. Profile Proxy — Serves the UCP profile and proxies checkout requests
  3. Pairing — Securely pairs your store with Sarvex

Installation

Step 1: Download and Upload

  1. Download the plugin directory from the Sarvex repository
  2. Extract it to your WordPress wp-content/plugins/ directory
  3. The plugin should appear in your WordPress Admin dashboard under Plugins

Step 2: Activate the Plugin

  1. Go to Plugins in the WordPress Admin
  2. Find Sarvex UCP Gateway
  3. Click Activate

Upon activation, the plugin will create the required configuration entries in your WordPress database.

Configuration

After activation, navigate to Sarvex UCP in the WordPress Admin menu to configure your store.

Required Settings

Sarvex Endpoint URL

  • What it is: The URL of your Sarvex backend server
  • Format: https://sarvex.example.com (no trailing slash)
  • Example: https://api.sarvex.example.com
  • Required: Yes

Pairing Code

  • What it is: A unique code generated by the plugin for pairing with Sarvex
  • How to use: Provide this code to Sarvex during the pairing process
  • Status: Read-only (displayed automatically)
  • Expires: This code is valid until you pair with Sarvex

How to Pair Your Store

  1. Get your Pairing Code

    • Navigate to Sarvex UCP settings in WordPress Admin
    • Copy the Pairing Code displayed

  2. Complete Pairing with Sarvex

    • Provide the pairing code to your Sarvex account manager or use the Sarvex console
    • Submit your store URL: https://yourstore.example.com

  3. Verify Configuration

    • After pairing, the Merchant ID and HMAC Secret fields will populate automatically
    • Both fields will display as read-only (hidden for security)

  4. Start Sending Signals

    • Once paired, any product, price, or inventory changes will automatically signal to Sarvex
    • Check the plugin logs to verify signals are being sent

How It Works

Product and Inventory Signals

Whenever you:

  • Add or update a product — A product signal is sent
  • Update stock quantity — An inventory signal is sent
  • Change stock status (In Stock → Out of Stock) — An inventory signal is sent

The plugin automatically sends a lean signal to Sarvex ({"sku": "...", "entity_kind": "product"}). Sarvex pulls the full product details from your store, so the signal contains only the SKU and entity type.

Profile Serving and Proxying

/.well-known/ucp (Profile Endpoint)

  • Returns your store’s UCP profile configuration
  • Cached for 1 hour for resilience
  • If Sarvex is unreachable, serves the last-known-good profile
  • Never requires authentication

/ucp/v1/* (Checkout Requests)

  • Proxies checkout operations live to Sarvex
  • Not cached (always fresh)
  • Returns Sarvex’s response as-is to the agent

Troubleshooting

Signals Not Being Sent

Check pairing status:

  • Verify Sarvex Endpoint URL is set
  • Verify Merchant ID and HMAC Secret are populated (they appear after successful pairing)

Check network connectivity:

  • Verify your server can reach the Sarvex endpoint URL
  • Check firewall and proxy settings

Review logs:

  • Log location: /wp-content/uploads/sarvex-ucp.log
  • Check for errors like “Failed to send signal” or network timeouts

Pairing Code Not Accepted

  • Verify the code is correct — Copy it exactly from the WordPress Admin
  • Ensure it hasn’t expired — If pairing takes a long time, generate a new code by deactivating and reactivating the plugin
  • Check Sarvex backend — Confirm the pairing request reached your Sarvex server

Profile Not Loading

If profile is unavailable:

  • Check network connectivity to Sarvex endpoint
  • Verify X-Sarvex-* headers are being sent correctly
  • Review logs for Failed to fetch profile from Sarvex

If profile is cached:

  • The plugin will serve the last-known-good profile if Sarvex is temporarily unreachable
  • This is intentional (graceful degradation)
  • Check logs for Serving cached profile due to Sarvex unreachable

Checkout Requests Failing

Check request proxying:

  • Verify /ucp/v1/* requests are reaching Sarvex
  • Check response status codes in logs
  • Confirm HMAC headers are valid

Check Sarvex endpoint:

  • Verify the endpoint URL is correct
  • Confirm Sarvex is running and reachable

Security Considerations

HMAC Signing

  • All requests to Sarvex are signed with HMAC-SHA256
  • The HMAC Secret is stored securely in the WordPress database
  • Never share or expose your HMAC Secret

Credential Storage

  • Merchant ID and HMAC Secret are stored in WordPress wp_options
  • Ensure your WordPress database is backed up and access is restricted
  • Regularly rotate your HMAC Secret through Sarvex

Data in Signals

  • Product signals contain only the SKU and entity type
  • No payment credentials, PII, or sensitive data is sent in signals
  • All data is encrypted in transit (HTTPS)

Logging

The plugin logs all signals, profile fetches, and errors to:

/wp-content/uploads/sarvex-ucp.log

Log format:

[2026-06-15 14:30:45] [INFO] Signal sent {"signal":{"sku":"ABC123","entity_kind":"product"},"sequence":5}
[2026-06-15 14:31:00] [WARN] Failed to fetch profile from Sarvex {"error":"Connection timeout"}

Development

Running Tests

cd plugin/woocommerce
phpunit tests/

Plugin Structure

plugin/woocommerce/
├── sarvex-ucp-gateway.php      # Main plugin file
├── src/
│   ├── Autoloader.php          # PSR-4 autoloader
│   ├── Plugin.php              # Main orchestrator
│   ├── Logger.php              # Logging utility
│   ├── HMAC.php                # HMAC signing
│   ├── SignalSender.php        # Product/inventory signals
│   ├── PairingManager.php      # Pairing handshake
│   └── ProfileProxy.php        # Profile serving and request proxying
├── tests/
│   ├── HMACTest.php
│   ├── PairingManagerTest.php
│   └── ProfileProxyTest.php
└── README.md                    # This file

Support

For issues or questions:

  1. Check the logs — /wp-content/uploads/sarvex-ucp.log
  2. Verify configuration — Ensure all required fields are populated
  3. Contact Sarvex support — Provide logs and configuration details (sanitize HMAC secret)

License

This plugin is part of Sarvex and is licensed under the Apache License 2.0.

Note: the WordPress.org plugin directory requires GPL-compatible licensing, so this plugin is distributed from this repository rather than that directory.

Was this page helpful?