How to Fix "UCP payment_handlers missing or empty"

What are UCP payment_handlers?

payment_handlers is a required array in your UCP manifest that declares every payment method your store accepts. Each entry is a reverse-domain identifier - like com.google.pay for Google Pay or dev.shopify.card for Shopify's card handler.

When an AI shopping agent reads your manifest, it checks this array to answer one question: "Can I actually complete a purchase here?" The array sits inside the Payment capability block:

{
  "capabilities": {
    "payment": {
      "spec_origin": "https://ucp.dev",
      "endpoint": "https://yourstore.com/api/ucp/payment",
      "payment_handlers": [
        "com.stripe.pay",
        "com.paypal.checkout"
      ]
    }
  }
}

Why this breaks AI agent purchases

AI agents don't guess payment methods. They read your declared handlers and match them against the payment credentials the user has authorized. Step by step:

1. Agent discovers your store and reads the manifest
2. Agent sees payment_handlers: [] (or the field is missing entirely)
3. Agent checks: "Does this store support any payment method I can use?"
4. Answer: "No payment methods declared."
5. Agent tells the user the store doesn't support a payment method it can process - or simply skips your store

Even if the rest of your manifest is perfect, an empty payment_handlers array means AI agents cannot transact. Your store is discovered but unfundable - functionally the same as invisible.

The 4 types of payment_handlers failures

1. Empty array (most common)

{ "payment_handlers": [] }

Valid JSON, field exists - but it tells agents you accept zero payment methods. This happens most often when a platform or plugin auto-generates a skeleton manifest without populating handlers.

2. Missing entirely

The field isn't present at all in the Payment capability. Agents treat this identically to an empty array. The UCP spec requires this field for any profile supporting Payment capability.

3. Wrong handler namespaces

{ "payment_handlers": ["stripe", "paypal", "shop_pay"] }

These are NOT valid identifiers. The spec requires reverse-domain notation: com.stripe.pay, com.paypal.checkout, dev.shopify.shop_pay. Bare names are unrecognized and treated as if no handlers exist.

4. Declared handlers don't match actual setup

{ "payment_handlers": ["com.google.pay", "com.apple.pay"] }

Your manifest says you accept Google Pay and Apple Pay, but your store is on Shopify with Shopify Payments only. The agent attempts a Google Pay transaction and it fails. This is the hardest failure to catch - it passes structural, rules, and even network checks. Only simulation testing finds it.

How to fix payment_handlers

Fix 1: Declare every supported payment method

Shopify (with Shopify Payments):

{
  "payment_handlers": [
    "dev.shopify.card",
    "dev.shopify.shop_pay",
    "com.google.pay",
    "com.apple.pay"
  ]
}

Stripe-powered: ["com.stripe.pay"]. WooCommerce with multiple gateways: ["com.woocommerce.txpg", "com.paypal.checkout", "com.stripe.pay"].

Fix 2: Use correct reverse-domain namespaces

Fix 3: Match handlers to your actual infrastructure

This is the step most guides skip. List every payment method your store actually processes, map each to its correct namespace, and declare ONLY those - no aspirational methods. Adding com.google.pay when you don't support it causes agent-side failures invisible in your own testing.

Fix 4: Verify handlers work through UCP endpoints

Your payment endpoint must receive payment requests from agents, route them to the correct handler based on the declared namespace, and return standardized responses. If your endpoint only handles a different handler or returns errors, agents fail at the network level.

How to test your fix

Payment handler failures span multiple levels. Level 1 and 2 catch empty arrays and bad namespaces. Level 3 and 4 are where the mismatch between declared handlers and actual infrastructure shows up - if you declare com.google.pay but don't support it, only a full simulation catches the failure. See the four levels of UCP validation.

Common related failures

• Missing signing_keys - agents need cryptographic verification before processing payments
• Namespace/origin mismatch - a handler declared under a mismatched origin is treated as untrusted
• Broken Identity Linking - blocks personalized checkout for recognized customers
• HTTP instead of HTTPS - all UCP payment endpoints require HTTPS

Last updated: May 2026. UCP spec version 1.2. payment_handlers is a required field within the Payment capability. Empty or missing arrays cause agents to skip your store in purchase flows - structural validation alone does not detect this. UCPtools is an independent community tool - not affiliated with Google, Shopify, or the UCP consortium.