Architectural Question: How do platforms support custom payment handlers for native checkout?

[SumuduLansakara]

Hi everyone,

I'm reviewing the UCP specification around the checkout lifecycle and am looking for clarification on how agentic platforms are expected to support custom payment handlers defined by payment processors.

Specifically, I'm trying to understand the execution boundaries when different payment methods require different custom instrument schemas containing sensitive user input (e.g. raw card details, bank account details or other local payment method-specific credentials).

Context

In a typical non-agentic checkout flow, the user first selects their preferred payment method (e.g. Card, SEPA Direct Debit or another local payment method). That selection determines which instrument schema must be collected. For example:

• Card → raw card details
• SEPA Direct Debit → bank account details

If such a payment processor wants to support agentic payments via UCP, the protocol expects it to define a custom payment handler that exposes all supported payment methods and their corresponding instrument schemas.

The question

When an agentic platform encounters such a custom payment handler, how is it expected to orchestrate the checkout lifecycle while maintaining an autonomous flow and still allowing the payment processor to receive all the information required to process the payment? More specifically:

1. Payment method discovery & instrument collection: How is the platform expected to discover the available payment methods, allow the user to select one, determine the corresponding instrument schema and securely collect the required inputs? Who is responsible for rendering the secure input fields defined by those schemas?

2. Tokenization & compliance: Once the required instrument has been collected, who is responsible for tokenizing it? Is the payment handler always expected to specify a tokenization endpoint owned by the payment processor, allowing the platform to submit the collected user input to that endpoint and then include the returned token in the checkout completion request?

Dilemma

I understand there's an alternative approach where the platform avoids calling the checkout completion endpoint by using requires_escalation together with continue_url. However, this largely defeats the purpose of an autonomous, seamless checkout flow, as responsibility for collecting the payment instrument shifts back to the merchant (either directly or by redirecting the user to a processor-hosted page).

On the other hand, requiring the platform to collect sensitive payment credentials seems to conflict with the intended trust model, as it introduces significant security, compliance, and liability considerations.

At the moment, I don't see how an agentic platform can support arbitrary custom payment handlers without implementing handler-specific logic. But, this also doesn't seem practical given that there can be many platforms and a large number of custom payment handlers.

Am I missing an intended protocol mechanism that addresses this, or is handler-specific integration the expected model?

I'd really appreciate any clarification on the intended architecture and responsibilities here.

Thanks!

[yhay81]

Your conclusion is essentially right: a UCP payment handler is not a remotely executable UI/plugin that every platform can consume generically. It is a named protocol contract. A platform supports a handler only after implementing that handler's acquisition/processing contract and advertising it in its own profile.

The intended flow is:

1. The platform advertises the handlers and instrument types it actually supports.
2. The business intersects those capabilities with its own configuration and checkout context.
3. The checkout response returns the authoritative available_instruments.
4. The user selects one of those resolved instruments.
5. The platform follows that handler's specified instrument-acquisition flow and submits the resulting instrument/credential.

The handler JSON Schema describes the data shapes; it does not, by itself, define a safe universal form renderer or transfer executable handler code to the platform. Therefore an unknown custom handler should not suddenly make arbitrary sensitive fields collectable. There must already be a mutually supported implementation.

For sensitive input, the main platform application/agent is not supposed to see raw credentials. The current examples put collection in a compliant secure payment credential provider/vault. Which party tokenizes is handler-specific:

• Processor tokenizer: the platform's secure credential provider collects the input and calls the processor/business /tokenize endpoint; the checkout receives the returned token.
• Platform tokenizer: the platform's compliant vault tokenizes internally; the business/PSP later detokenizes under binding/auth rules.
• Encrypted credential: the compliant vault encrypts directly to the business's public key; no tokenization round trip.
• Escalation/continue URL: appropriate when no mutually supported autonomous acquisition mechanism exists or user interaction must move elsewhere.

So a processor-owned tokenization endpoint is a valid and documented pattern, but it is not an automatic property of every custom handler. The handler specification must define its participants, prerequisites/onboarding, acquisition protocol, endpoints/authentication, credential transformation, binding, and compliance responsibilities. Platforms that have not implemented/onboarded that handler cannot honestly advertise support for it.

In short: UCP gives you N-to-N capability discovery and standard envelopes, not zero-code universal execution. A seamless autonomous flow exists only for the intersection of handlers both sides have implemented; otherwise escalation is the correct boundary, not a failure of the protocol.

Relevant current spec sections:

• Payment Handler Guide — participants, declaration variants, and capability resolution
• Processor Tokenizer example
• Platform Tokenizer example
• Encrypted Credential example

[SumuduLansakara]

Hi Yusuke,

Thanks for taking the time to write out such a detailed breakdown and pointing to those specific handler guide sections.

The distinction you highlighted, that UCP contracts are named, mutually implemented agreements rather than zero-code remote UI plugins, makes complete sense from a security and compliance perspective. It cleanly resolves the trust and tokenization boundaries (whether via processor tokenizers, platform vaults or direct encryption payloads).

However, looking at this from the perspective of scaling across a broad ecosystem of alternative and local payment methods, this model introduces a heavy friction point. If every unique payment method or custom instrument schema requires a pre-integrated, handler-specific implementation on the platform side, it severely limits the "plug-and-play" network effect for anything outside major global rails.

While requires_escalation + continue_url provide a safe escape hatch, relying on them as the default for un-integrated methods effectively forfeits the autonomous agentic UX entirely.

Given this architecture, do you see the protocol evolving toward any standardized, extensible instrument acquisition primitives that allow platforms to handle long-tail or dynamic local payment schemas without requiring bespoke handler code for every single provider? Or is tight, point-to-point integration strictly expected to be the permanent gatekeeper for autonomous flows?

Thanks again for the great discussion!