UCP payment handlers: specifications, instruments, PSPs

Why UCP declares processing specifications rather than providers, what a payment handler contains, and what it changes about choosing a PSP.

Published 1 August 2026 . Part of agentic payments.

Inside the /.well-known/ucp manifest, one registry carries the whole weight of the transaction: payment_handlers. The specification defines it in terms worth reading literally, because they invert the intuition of most ecommerce teams.

Payment Handlers are specifications (not entities) that define how payment instruments are processed.

Specifications, not entities. A payment handler does not say “I route through this provider”. It says “here is how this class of instrument is processed on my side”. The difference is not cosmetic, and it has direct consequences for architecture and for contracts.

What an entry contains

Each declared handler combines six fields, per the 2026-04-08 specification:

Field	Role
`id`	handler identifier
`version`	version of the processing specification
`spec`	URL of the specification followed
`schema`	associated validation schema
`available_instruments`	instruments actually accepted
`config`	merchant-specific parameters

The split between spec and available_instruments is the heart of the design. The first says how processing works. The second says what is accepted today. A merchant can follow a broad processing specification while opening only a subset of instruments, then widen without changing specification.

Why “specification” and not “provider”

The usual ecommerce model couples acceptance to the vendor: you wire up a PSP, and the list of available payment methods follows from its catalogue. Migrating PSP then means redoing the integration, and often reworking the checkout flow.

UCP moves the contract up one level. What the agent reads is how payment proceeds, not the identity of whoever executes it. The practical consequence: switching provider does not necessarily change the manifest, as long as the declared processing specification stays the same. The agent keeps seeing the same contract; the plumbing changes underneath.

This is a protocol design decision consistent with the rest of UCP, where the merchant remains the source of truth. It carries a less comfortable corollary: it is the merchant, not the PSP, who must guarantee that declared behaviour matches real behaviour. An optimistic declaration will be paid for in negotiation failures on the agent side.

What the specification does not say

Be precise about the limits of what the manifest establishes, because that is where the unpleasant surprises live.

The manifest declares a technical processing contract. It does not assign liability in a dispute, it does not define who absorbs a chargeback, and it states no fraud-risk sharing rule. Those questions belong to network rules and acquiring contracts, not to the protocol. The authorisation layer they rest on is described on the AP2 page.

The specification does contain one explicit scoping principle, surfaced in reference implementations: a manifest represents exactly one merchant, precisely to keep liability and ownership clearly attributed. A marketplace operator hoping to expose several sellers behind a single manifest is therefore working against the model.

How it combines with existing rails

UCP declares the processing; agent-aware rails supply the instrument and the proof of authorisation. The two layers complement each other rather than compete.

AP2 supplies the signed mandates that prove user authorisation.
Visa Intelligent Commerce and Mastercard Agent Pay supply agent-linked card credentials, on the network side.
On the ACP side, the equivalent function sits in a delegate payment specification kept separate from the checkout specification, visible in the OpenAPI layout of the reference repository.

Reading payment_handlers as a PSP choice is therefore a level error. It is a choice of processing contract, upstream of the vendor choice.

Three questions to settle before declaring

Does the declared specification describe what checkout actually does? Including the non-nominal paths: partial authorisation, amount adjustment, refund.
Does available_instruments reflect production acceptance? An instrument declared but refused in practice produces a failure at the end of the journey, at the worst moment.
Is handler versioning aligned with the release cycle? UCP negotiation keeps the highest mutually supported version: publishing a version production does not serve yet creates a silent gap.

For the negotiation mechanics that consume these declarations, see the note on the UCP manifest. For the landscape of rails, see agentic payments.

Sources

Back to agentic payments · All notes · Lire en français