|
What is UCP?
The Universal Commerce Protocol (UCP) is an open standard co-developed by Google, Shopify, Etsy, Wayfair, Target, Walmart and endorsed by over 40 companies including Stripe, PayPal, Visa, Mastercard, Best Buy, Macy's and many more.
UCP establishes a common language for AI agents, platforms and businesses to interact. It allows AI assistants (such as Google Gemini, ChatGPT, Claude and others) to discover products on your store, create carts, process checkout and handle payments on behalf of their users : all through a standardized API.
In practice, this means a customer can say to their AI assistant "find me a blue jacket under $100" and the AI can search your store, show matching products, and guide the customer through checkout without them ever needing to visit your website directly.
HikaShop implements UCP through a system plugin that exposes the necessary API endpoints. Once enabled and configured, your store becomes discoverable and purchasable by any UCP-compatible AI agent.
How it works
UCP works through a set of REST API endpoints that your store exposes. AI agents interact with these endpoints to perform commerce operations. Here is an overview of the different components and how they communicate:
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ │ │ │ │ │ │ │
│ Customer │ │ AI Agent │ │ Your HikaShop │ │ Payment Gateway │
│ │ │ (Gemini, │ │ Store + UCP Plugin │ │ (Stripe, │
│ │ │ Claude, │ │ │ │ Worldline) │
│ │ │ etc.) │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ └────────┬─────────┘
│ │ │ │
│ "Find me a │ │ │
│ blue jacket" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ GET /.well-known/ucp │ │
│ │───────────────────────>│ │
│ │ Discovery response │ │
│ │<───────────────────────│ │
│ │ │ │
│ │ POST /ucp/v1/search │ │
│ │ { "query": "blue │ │
│ │ jacket" } │ │
│ │───────────────────────>│ │
│ │ Product results │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Here are 3 │ │ │
│ options..." │ │ │
│<───────────────────│ │ │
│ │ │ │
│ "I'll take the │ │ │
│ second one" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ POST /checkout-sessions│ │
│ │ { items, buyer, │ │
│ │ shipping address } │ │
│ │───────────────────────>│ │
│ │ Session with totals │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Total is $79. │ │ │
│ Confirm?" │ │ │
│<───────────────────│ │ │
│ │ │ │
│ "Yes, pay with │ │ │
│ Google Pay" │ │ │
│───────────────────>│ │ │
│ │ │ │
│ │ POST /complete │ │
│ │ { payment credential }│ │
│ │───────────────────────>│ │
│ │ │ Process payment │
│ │ │─────────────────────────>│
│ │ │ Payment confirmed │
│ │ │<─────────────────────────│
│ │ Order confirmed │ │
│ │<───────────────────────│ │
│ │ │ │
│ "Done! Order │ │ │
│ #1234 placed." │ │ │
│<───────────────────│ │ │
│ │ │ │
The purchase flow
Here is a closer look at what happens during each step of the UCP purchase flow between the AI agent and your HikaShop store:
AI Agent HikaShop UCP Plugin
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 1: DISCOVERY │ │
│ │ The AI agent discovers your store's capabilities │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ GET /.well-known/ucp │
│──────────────────────────────────────────────────────>│
│ │ Reads plugin config,
│ │ detects Google Pay gateway,
│ { │ builds capability list
│ "ucp": { │
│ "version": "2026-01-11", │
│ "capabilities": [ │
│ "dev.ucp.shopping.catalog", │
│ "dev.ucp.shopping.checkout", │
│ "dev.ucp.shopping.payment" │
│ ] │
│ }, │
│ "payment": { "handlers": ["com.google.pay"] } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 2: PRODUCT SEARCH │ │
│ │ The AI searches for products matching the │ │
│ │ customer's request │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/search │
│ { "query": "blue jacket", "limit": 10 } │
│──────────────────────────────────────────────────────>│
│ │ Searches products,
│ { │ applies stock/access
│ "products": [ │ filters, formats
│ { "id": "gid://site/Product/42", │ prices in cents
│ "name": "Classic Blue Jacket", │
│ "price": { "amount": 7900, "currency":"USD" }, │
│ "availability": "in_stock", │
│ "images": [...] } │
│ ], │
│ "total": 3 │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 3: CREATE CHECKOUT SESSION │ │
│ │ A cart is created with the selected products, │ │
│ │ buyer info, and shipping address │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/checkout-sessions │
│ { │
│ "line_items": [ │
│ { "item": { "id": "gid://.../42" }, │
│ "quantity": 1 } │
│ ], │
│ "buyer": { │
│ "email": "john@example.com", │
│ "first_name": "John" }, │
│ "fulfillment": { │
│ "methods": [{ │
│ "type": "shipping", │
│ "destinations": [{ │
│ "country": "US", │
│ "postal_code": "10001", │
│ "street_address": "123 Main St" }] │
│ }] │
│ } │
│ } │
│──────────────────────────────────────────────────────>│
│ │ Creates UCP cart,
│ { │ assigns user,
│ "id": "gid://site/Checkout/99", │ calculates taxes
│ "status": "incomplete", │ and shipping options
│ "totals": [ │
│ { "type": "subtotal", "amount": 7900 }, │
│ { "type": "tax", "amount": 632 }, │
│ { "type": "fulfillment", "amount": 500 }, │
│ { "type": "total", "amount": 9032 } │
│ ], │
│ "fulfillment": { │
│ "options": [ │
│ { "id": "5", "name": "Standard", ... }, │
│ { "id": "8", "name": "Express", ... } │
│ ] │
│ } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ STEP 4: COMPLETE CHECKOUT │ │
│ │ The order is created and payment is processed │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ POST /ucp/v1/checkout-sessions/99/complete │
│ { "payment_method_id": "gid://.../7", │
│ "payment_data": { │
│ "handler_id": "com.google.pay", │
│ "credential": { "token": "..." } │
│ } │
│ } │
│──────────────────────────────────────────────────────>│
│ │ Creates order from cart,
│ { │ sends payment token to
│ "status": "completed", │ gateway, confirms order
│ "order": { │
│ "id": "gid://site/Order/1234", │
│ "permalink_url": "https://..." } │
│ } │
│<──────────────────────────────────────────────────────│
│ │
Payment flows
UCP supports two different payment flows depending on how the payment gateway works:
Direct token flow (Google Pay)
The AI agent's platform (e.g., Google) obtains a payment token from the customer's wallet and sends it directly in the checkout completion request. The payment plugin processes the token server-side without any customer redirect. This is the fastest and most seamless flow.
AI Agent HikaShop Payment Gateway
│ │ │
│ POST /complete │ │
│ { token: "..." } │ │
│────────────────────>│ │
│ │ Charge token │
│ │───────────────────────>│
│ │ Payment confirmed │
│ │<───────────────────────│
│ Order confirmed │ │
│<────────────────────│ │
│ │ │
Hosted checkout flow
When no payment token is available, the AI agent receives a hosted checkout URL from the payment gateway. The customer is redirected to the gateway's secure page to complete payment. After payment, the gateway notifies HikaShop via webhook.
AI Agent HikaShop Payment Gateway Customer
│ │ │ │
│ POST /complete │ │ │
│ { method_id only } │ │ │
│────────────────────>│ │ │
│ │ Create hosted session │ │
│ │───────────────────────>│ │
│ │ Hosted checkout URL │ │
│ │<───────────────────────│ │
│ continue_url │ │ │
│<────────────────────│ │ │
│ │ │ │
│ Redirect customer │ │ │
│─────────────────────────────────────────────────────────────────>│
│ │ │ Customer pays │
│ │ │<──────────────────│
│ │ Webhook notification │ │
│ │<───────────────────────│ │
│ │ Order confirmed │ │
│ │ │ │
Setting up UCP on your website
Setting up UCP on your HikaShop store involves enabling the plugin, configuring a few settings, and making sure you have a compatible payment method. Here are the steps:
1. Install and enable the plugin
The UCP plugin is included with HikaShop. Go to Extensions > Plugins in your Joomla backend and search for "HikaShop UCP". Enable the plugin by clicking on the status icon.
On WordPress, go to Plugins and make sure the HikaShop UCP plugin is activated.
2. Configure the plugin
Open the plugin settings and configure the following:
- API Key: Set a secret key that AI agents will use to authenticate their requests. If left empty, the API will be accessible without authentication (not recommended for production as it can lead to spam orders on your shop).
- Base Path: The URL path for the REST API endpoints. Default is
/ucp/v1. You generally don't need to change this. - Privacy Policy URL and Terms of Service URL: Links to your store's legal pages. These are included in the UCP discovery response so that AI agents can present them to customers. These should be provided.
Google Pay settings
If you want to enable Google Pay as a payment handler (recommended), configure these additional settings:
- Enable Google Pay: Set to Yes.
- Environment: Use TEST for development, switch to PRODUCTION for your live store.
- Merchant ID: Your Google Pay merchant ID from the Google Pay Business Console.
- Merchant Name: Your business name as it should appear in Google Pay.
- Card Networks: The card types you accept (Visa, Mastercard, Amex, Discover, JCB).
- Auth Methods: PAN_ONLY (cards saved in Google Account) and/or CRYPTOGRAM_3DS (device tokens from Android phones).
3. Set up a compatible payment plugin
You need at least one UCP-compatible payment plugin installed and configured. Currently, two payment plugins support UCP:
See the Compatible payment plugins section below for details on each.
4. Verify your setup
Once the plugin is enabled and configured, you can verify your setup by accessing the discovery endpoint in your browser:
https://www.yoursite.com/.well-known/ucp
You should see a JSON response listing your store's UCP capabilities, the supported services, and the available payment handlers. If Google Pay is properly configured, you should see it listed under the payment.handlers section.
Connecting to AI platforms
Once UCP is set up on your store, AI platforms need to know about it. The process differs depending on the platform.
Google (Gemini, Search AI Mode)
Google is one of the first platforms to support UCP natively for shopping. To connect your HikaShop store to Google's AI surfaces (Gemini, Search AI Mode), you need to:
- Set up Google Merchant Center: You need a Google Merchant Center account in good standing with approved products listed for free listings. Configure your shipping settings, return policies, and customer support information.
- Configure the HikaShop Google Products plugin: This plugin generates the product feed that Google Merchant Center uses to index your products. Make sure it is installed, enabled, and properly configured. See the Google Products plugin documentation for setup instructions. When the UCP plugin is enabled, the Google Products plugin automatically adds the
native_commerceattribute to all products in the feed, which signals to Google that they are eligible for UCP checkout. - Set up Google Pay: Create a business account in the Google Pay & Wallet Console. Note your Google Pay Merchant ID : you will need it for the UCP plugin's Google Pay settings.
- Join the Google UCP program: Google requires merchants to go through an approval process before their UCP integration can go live. Visit the Google UCP developer guide to fill out the interest form and get in contact with Google's team.
- Google discovers your store automatically: Once approved, Google crawls your
/.well-known/ucpendpoint to discover your store's capabilities, available services, payment handlers, and product catalog. You do not need to paste any token or URL into Google Merchant Center : the discovery is automatic based on your domain.
Note: Authentication between Google and your store uses cryptographic signing keys (JWK format) published in your /.well-known/ucp manifest, not the API key from the plugin settings. Google verifies webhooks and messages using these public keys. The UCP plugin handles this automatically.
Other AI agents
For other AI platforms and agents that support UCP (or any custom integration), the process is simpler:
- Share your API key: The API key configured in the UCP plugin settings is what other AI agents use to authenticate against your store's REST API. Share it with whichever platform you want to grant access to.
- Provide your discovery URL: Give them your store's discovery endpoint:
https://www.yoursite.com/.well-known/ucp. The AI agent will call this to discover your store's capabilities and API endpoints. - MCP-compatible agents: If the AI agent supports MCP (Model Context Protocol) : like Claude : you can enable the MCP endpoint in the plugin settings and provide the MCP URL instead (see MCP support).
Since UCP is an open standard, any AI platform that implements the specification can interact with your store. As more platforms adopt UCP, your store will be accessible to a growing number of AI agents without any additional configuration.
Plugin settings reference
| Setting | Description | Default |
|---|---|---|
| API Key | Secret key for authenticating API requests. Sent by AI agents via the X-API-KEY header. Leave empty for open access. |
empty |
| Base Path | URL path prefix for all REST endpoints (e.g., /ucp/v1). |
/ucp/v1 |
| Enable MCP | Enables the Model Context Protocol (MCP) JSON-RPC endpoint for AI-native integration. See MCP support. | No |
| MCP Slug | URL slug for the MCP endpoint (e.g., /ucp-mcp). |
ucp-mcp |
| Privacy Policy URL | Link to your privacy policy. Included in the discovery response. | empty |
| Terms of Service URL | Link to your terms of service. Included in the discovery response. | empty |
| Enable Google Pay | Advertise Google Pay as a payment handler in UCP discovery. | No |
| Google Pay Environment | TEST for sandbox testing, PRODUCTION for live payments. | TEST |
| Google Pay Merchant ID | Your merchant ID from the Google Pay Business Console. | empty |
| Google Pay Merchant Name | Business name displayed in Google Pay. | empty |
| Card Networks | Accepted card types for Google Pay. | VISA, MASTERCARD |
| Auth Methods | PAN_ONLY (cards in Google Account) and/or CRYPTOGRAM_3DS (device tokens). | PAN_ONLY, CRYPTOGRAM_3DS |
Compatible payment plugins
For UCP to process payments, you need a payment plugin that supports at least one of the UCP payment flows: the direct token flow (for Google Pay) and/or the hosted checkout flow (for redirect-based payments). Currently, two plugins support UCP:
Stripe Checkout
Available on the HikaShop marketplace
The Stripe Checkout plugin supports both UCP payment flows:
- Direct token flow: Processes Google Pay tokens via the Stripe PaymentIntents API. Supports 3D Secure challenges when required by the card issuer.
- Hosted checkout flow: Generates a Stripe Checkout Session URL where the customer can pay using any method supported by Stripe (cards, Apple Pay, Google Pay, bank transfers, etc.).
Setup for UCP: Make sure your Stripe plugin is configured with a valid Publishable Key and Secret Key. The publishable key is automatically used as the Google Pay gateway merchant ID. No additional UCP-specific configuration is needed in the Stripe plugin itself : UCP support is built-in.
Note: The Stripe Checkout plugin uses the gateway identifier stripe for Google Pay tokenization. Stripe handles all PCI compliance and token decryption on their servers.
Worldline Direct
Available on the HikaShop marketplace
The Worldline Direct plugin (formerly Ingenico Direct) also supports both UCP payment flows:
- Direct token flow: Processes Google Pay encrypted tokens via the Worldline CreatePayment API. Automatically handles 3D Secure authentication for PAN_ONLY tokens. Supports redirect-based 3DS challenges when required.
- Hosted checkout flow: Generates a Worldline hosted checkout page URL where the customer can pay using cards and other methods supported by Worldline.
Setup for UCP: Make sure your Worldline Direct plugin is configured with a valid PSPID, API Key, API Secret, and Webhook Secret. The PSPID is automatically used as the Google Pay gateway merchant ID. No additional UCP-specific configuration is needed in the Worldline plugin itself.
Note: The Worldline Direct plugin uses the gateway identifier worldline for Google Pay tokenization. Worldline uses product code 320 for Google Pay payments.
Making other payment plugins UCP-compatible
Payment plugin developers can add UCP support to their plugins by implementing up to three methods in their payment plugin class:
getPaymentURL(&$order, &$method): Return a hosted checkout URL for the order.onUcpPaymentProcess(&$order, &$paymentContext, &$paymentResult): Process a payment token directly.getUcpGooglePayConfig(): Return the Google Pay gateway configuration (gateway name and merchant ID).
All three methods are optional. A plugin can support just the hosted checkout flow, just the direct token flow, or both. You can base yourself on the example payment plugin.
MCP support
In addition to the REST API, HikaShop's UCP plugin can optionally expose an MCP (Model Context Protocol) endpoint. MCP is a JSON-RPC based protocol designed for AI models to interact with external tools natively. It is the protocol used by AI assistants like Claude to call external tools.
When MCP is enabled, AI agents can interact with your store using MCP tools instead of REST calls. The following tools are available:
create_checkout: Create a checkout sessionget_checkout: Retrieve a checkout sessionupdate_checkout: Update a checkout sessioncomplete_checkout: Complete checkout and create an ordercancel_checkout: Cancel a checkout sessionlist_payment_methods: List available payment methods
To enable MCP, set Enable MCP to Yes in the plugin settings and configure the MCP Slug (default: ucp-mcp). The MCP endpoint will be available at https://www.yoursite.com/ucp-mcp.
Security
The UCP plugin includes several security mechanisms:
- API key authentication: All REST and MCP endpoints (except the discovery endpoint at
/.well-known/ucp) require a valid API key. The key is sent via theX-API-KEYheader or as akeyquery parameter. We strongly recommend setting an API key for production stores. - Session binding: Each UCP checkout session is bound to a unique session token. This prevents unauthorized access to other customers' carts.
- Idempotency: The plugin supports an
Idempotency-Keyheader on checkout session creation. Sending the same key within 24 hours returns the existing session instead of creating a duplicate, preventing double orders from network retries. - Payment security: Payment tokens (such as Google Pay tokens) are encrypted by the payment gateway and can only be decrypted by the gateway's servers. HikaShop never sees or stores raw card details.
FAQ
Do customers need an account on my store?
No. The UCP plugin automatically creates a HikaShop user from the buyer's email address provided by the AI agent. If a user with that email already exists, the existing account is used.
Which AI assistants support UCP?
UCP is an open standard supported by a growing number of AI platforms. Google Gemini and Google Search AI Mode are among the first to support UCP natively for shopping. Any AI agent that implements the UCP specification can interact with your store.
Can I use UCP without Google Pay?
Yes. Google Pay is optional. Without it, the hosted checkout flow is still available: the AI agent receives a payment URL and redirects the customer to the payment gateway's page to complete payment.
Does UCP work with product variants?
Yes. Product variants are returned in search results with their own IDs, prices, and availability. AI agents can add specific variants to the cart.
Are discount codes / coupons supported?
Yes. AI agents can apply a discount code when creating or updating a checkout session. The discount is validated and applied just like it would be during a normal checkout.
Where can I learn more about the UCP specification?
Visit ucp.dev for the full specification, or browse the GitHub repository for technical details and code samples.
