UCP Payment Handlers: A Complete Developer Guide for 2026

What a Payment Handler Actually Does

In UCP, a payment handler is any service that can accept a payment token and authorize a transaction. The term is broader than "payment processor." It includes:

• Card acquirers (Stripe, Adyen, Worldpay)
• Card networks (Visa, Mastercard)
• Digital wallets (Apple Pay, PayPal)
• BNPL providers (Klarna, Affirm, Afterpay)
• Payment orchestrators (Primer, Spreedly)
• Regional payment methods (Nuvei for APMs, Mollie for European methods)

The merchant declares which payment handlers it accepts in its UCP manifest. The agent presents the consumer's pre-authorized payment token to the merchant's checkout endpoint. The merchant routes the token to the appropriate handler.

Reading the Payment Handler Section of a UCP Manifest

A live UCP manifest at /.well-known/ucp includes a paymentHandlers array:

{
  "merchantId": "merch_abc123",
  "capabilities": ["checkout", "identity-linking"],
  "paymentHandlers": [
    { "id": "com.stripe", "name": "Stripe", "regions": ["global"] },
    { "id": "com.klarna", "name": "Klarna", "regions": ["eu", "us"] },
    { "id": "com.paypal", "name": "PayPal", "regions": ["global"] }
  ],
  "checkoutEndpoint": "https://store.example.com/ucp/checkout"
}

The id field is the canonical payment handler identifier. Your agent should check whether the consumer's pre-authorized payment token matches one of the listed handler IDs before initiating checkout. If there is no match, the checkout will fail.

async function canCheckout(
  manifest: UcpManifest,
  consumerPaymentToken: UcpPaymentToken
): Promise<boolean> {
  return manifest.paymentHandlers.some(
    (handler) => handler.id === consumerPaymentToken.handlerId
  );
}

Handler Selection When Multiple Tokens Are Available

A consumer might have multiple payment tokens pre-authorized: a Stripe token for their Visa card, a PayPal token, and a Klarna token. When multiple tokens match the merchant's accepted handlers, your agent needs a selection strategy.

Default strategies:

1. Prefer the last-used handler. Check the agent platform's transaction history for this merchant and use the same handler.
2. Prefer the handler with the lowest fee. Payment handlers expose fee information in the UCP token metadata when available.
3. Ask the consumer. For purchases above the consumer's confirmation threshold, present the handler options as part of the confirmation prompt.

function selectPaymentToken(
  acceptedHandlers: PaymentHandler[],
  consumerTokens: UcpPaymentToken[],
  transactionHistory: TransactionRecord[],
  merchantId: string
): UcpPaymentToken | null {
  const matchingTokens = consumerTokens.filter((token) =>
    acceptedHandlers.some((h) => h.id === token.handlerId)
  );

  if (matchingTokens.length === 0) return null;

  // Prefer most recently used at this merchant
  const lastUsed = transactionHistory
    .filter((t) => t.merchantId === merchantId)
    .sort((a, b) => b.timestamp - a.timestamp)[0];

  if (lastUsed) {
    const preferred = matchingTokens.find(
      (t) => t.handlerId === lastUsed.handlerId
    );
    if (preferred) return preferred;
  }

  return matchingTokens[0];
}

Regional Coverage

Not all payment handlers operate in all regions. A merchant in Germany likely accepts Mollie, Klarna, and SEPA-connected handlers. A US merchant may only accept Stripe and PayPal. Check the regions field on each handler before selecting a token.

Current UCP payment handler coverage by region:

United States
Stripe, PayPal, Braintree, Affirm, Klarna, Square

Europe (broad)
Adyen, Mollie, Checkout.com, Klarna, Worldpay

Global / Multi-region
Nuvei, Spreedly, Primer, Mastercard, Visa

Asia-Pacific
Ant International, Nuvei

MENA
Tabby, Tamara

Latin America
Nuvei via VTEX and other platform integrations

Handling Checkout Failures

Payment handler failures return specific error codes. Your agent needs to handle these explicitly rather than failing silently.

402 Payment Required with code token_insufficient_scope
The payment token does not cover this transaction amount or category. The consumer's token scope is too restrictive.

if (response.status === 402 && response.body.code === 'token_insufficient_scope') {
  await notifyConsumer({
    message: 'Your payment token limit is too low for this purchase. Increase your agent spending limit to proceed.',
  });
}

402 Payment Required with code handler_declined
The payment handler declined the transaction. This may indicate a fraud block, insufficient funds, or a card restriction. Do not retry automatically.

409 Conflict with code inventory_unavailable
The item went out of stock between catalog query and checkout. Retry with an alternative product or notify the consumer.

503 Service Unavailable
The payment handler is temporarily unavailable. Retry with exponential backoff up to three times, then notify the consumer rather than abandoning silently.

Building a Payment Handler Test Matrix

Before shipping your agent to consumers, test every payment handler your agent may encounter:

const TEST_HANDLERS = [
  'com.stripe',
  'com.paypal',
  'com.klarna',
  'com.adyen',
  'com.mollie',
];

for (const handlerId of TEST_HANDLERS) {
  const result = await testCheckoutFlow({
    merchantEndpoint: TEST_MERCHANT_ENDPOINT,
    paymentHandlerId: handlerId,
    amount: 1000, // $10 test transaction
  });

  console.log(`${handlerId}: ${result.status}`);
}

Use the UCP Demo Playground for test endpoints and the UCP Conformance Suite to verify your handler selection and error handling logic covers the full spec.

The UCPList directory shows which payment handlers are live versus announced. Filter by category to see the full list of active payment handler integrations before deciding which ones to support in your agent.