Payment Handler Specification Guide

Introduction

This guide defines the standard structure and vocabulary for specifying UCP payment handlers to ensure consistency, completeness, and clarity.

Purpose

Payment handlers enable “N-to-N” interoperability between platforms, businesses, and payment providers. A well-specified handler must answer:

  • Who participates? What participants are involved and their roles
  • What are the prerequisites? What onboarding or setup is required
  • How is it configured? What configuration is advertised or consumed
  • How is it executed? What protocol is followed

Core Elements

Participants

The distinct actors that participate in the payment handler’s lifecycle:

ParticipantRole
BusinessAdvertises handler configuration, processes payment instruments
PlatformDiscovers handlers, acquires payment instruments, submits checkout
Tokenizer (Optional)Stores raw credentials and issues token credentials
PSP (Optional)Processes payments on behalf of business

Prerequisites

The onboarding, setup, or configuration a participant must complete before participating:

Signature:

PREREQUISITES(participant, onboarding_input) → prerequisites_output

Output includes:

  • Identity (access_token in PaymentIdentity format)
  • Additional configuration, credentials, or settings

Handler Declaration

The configuration a business advertises to indicate support for this handler:

{
  "id": "handler_instance_id",
  "name": "com.example.handler",
  "version": "2026-01-11",
  "spec": "https://example.com/ucp/handler",
  "config_schema": "https://example.com/ucp/handler/config.json",
  "instrument_schemas": [
    "https://example.com/ucp/handler/instruments/card.json"
  ],
  "config": {
    // Handler-specific configuration
  }
}

Instrument Acquisition

The protocol a platform follows to acquire a payment instrument:

Signature:

INSTRUMENT_ACQUISITION(
  platform_prerequisites_output,
  handler_declaration,
  binding,
  buyer_input
) → checkout_instrument

Processing

The steps a participant takes to process a received payment instrument:

Signature:

PROCESSING(
  identity,
  checkout_instrument,
  binding,
  transaction_context
) → processing_result

Best Practices

Schema Design

PracticeDescription
Extend, don’t reinventUse allOf to compose base schemas
Use const for discriminatorsDefine credential.type as const
Validate earlyPublish schemas at stable URLs before finalizing
Include ExpiryInclude expiry or ttl for token credentials

Documentation

PracticeDescription
Show, don’t just tellInclude complete JSON examples
Document error casesSpecify error handling
Version independentlyHandler version evolves independently of UCP

Security

PracticeDescription
Require bindingTie credentials to specific checkout via binding
Minimize credential exposureDesign flows to minimize raw credential exposure
Specify token lifetimesDocument single-use, time-limited, or session-scoped

Conformance Checklist

Before publishing, verify:

  • Uses standard template structure
  • All [REQUIRED] sections are present
  • All participants listed with roles
  • Prerequisites documented for each participant
  • Identity maps to PaymentIdentity structure
  • Config, instrument, and credential schemas documented
  • Protocol steps enumerated with examples
  • Binding requirements specified
  • Security requirements listed
  • Handler name follows reverse-DNS convention

See Also