Payment Handler Specification Guide

Introduction

This guide defines the standard structure and vocabulary for specifying UCP payment handlers. All payment handler specifications SHOULD follow this structure to ensure consistency, completeness, and clarity for implementers.

Purpose

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

Who participates? What participants are involved and what are 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 to acquire or process instruments?

This guide provides a framework that ensures every handler specification answers these questions systematically.

Scope

This guide applies to:

Handlers (e.g., com.google.pay, dev.shopify.shop_pay) — Specific payment method implementations

Core Concepts

Every payment handler specification MUST define the core elements below.

Note on Protocol Signatures:: The function signatures provided in this section (e.g., PROCESSING(...)) represent logical data flows, not literal function calls. Spec authors must map these logical flows to the actual transport protocol used by their implementation.

+------------------------------------------------------------------------------+
|                        Payment Handler Framework                             |
+------------------------------------------------------------------------------+
|                                                                              |
|   +--------------+                                                           |
|   | PARTICIPANTS |  Who participates in this handler?                        |
|   +------+-------+                                                           |
|          |                                                                   |
|          v                                                                   |
|   +--------------+                                                           |
|   |PREREQUISITES |  How does each participant obtain identity & configs?     |
|   +------+-------+                                                           |
|          |                                                                   |
|          +--------------------+----------------------+                       |
|          v                    v                      v                       |
|   +--------------+    +--------------+      +--------------+                 |
|   |   HANDLER    |    |  INSTRUMENT  |      |  PROCESSING  |                 |
|   | DECLARATION  |    |  ACQUISITION |      |              |                 |
|   +--------------+    +--------------+      +--------------+                 |
|   Business advertises  platform acquires     Participant                     |
|   handler config       checkout instrument   processes instrument            |
|                                                                              |
+------------------------------------------------------------------------------+

Participants

Definition: The distinct actors that participate in the payment handler’s lifecycle. Every handler has at minimum two participants (business and platform), but MAY define additional participants with specific roles.

Note on Terminology:: While this guide refers to the participant as the “Business”, technical schema fields may retain the standard industry nomenclature merchant_* (e.g., merchant_id, merchant_name). Specifications MUST explicitly document these field mappings.

Standard Participants:

Participant	Role
Business	Advertises handler configuration, processes payment instruments
Platform	Discovers handlers, acquires payment instruments, submits checkout

Extended Participants (example handler-specific participants):

Participant	Example Role
Tokenizer	Stores raw credentials and issues token credentials
PSP	Processes payments on behalf of business using the checkout instrument

Prerequisites

Definition: The onboarding, setup, or configuration a participant must complete before participating in the handler’s flows.

Signature:

PREREQUISITES(participant, onboarding_input) → prerequisites_output

Field	Description
`participant`	The participant being onboarded (business, platform, etc.)
`onboarding_input`	What the participant provides during setup
`prerequisites_output`	The identity and any additional configuration received

Prerequisites Output:

The prerequisites_output contains what a participant receives from onboarding. At minimum, this includes an identity. It MAY also include additional configuration, credentials, or settings specific to the handler.

Payment handler specifications are not required to define a formal schema for prerequisites_output. Instead, the specification SHOULD clearly document:

What identity is assigned (and how it maps to PaymentIdentity)
What additional configuration is provided
How the prerequisites output is used in Handler Declaration, Instrument Acquisition, or Processing

Notes:

Prerequisites typically occur out-of-band (portals, contracts, API calls)
Multiple participants MAY have independent prerequisites
The identity from prerequisites typically appears within the handler’s config object (e.g., as merchant_id or similar handler-specific field)
Participants receiving raw credentials (e.g., businesses, PSPs) typically must complete security acknowledgements during onboarding, accepting responsibility for credential handling and compliance

Handler Declaration

Definition: The configuration a business advertises to indicate support for this handler and enable platforms to invoke it.

Signature:

HANDLER_DECLARATION(prerequisites_output) → handler_declaration

Field	Description
`prerequisites_output`	The identity and configuration from business prerequisites
`handler_declaration`	The handler object advertised in `ucp.payment_handlers`

Output Structure:

The handler declaration conforms to the PaymentHandler schema. The specification SHOULD define the available config and instrument schemas, and how to construct each based on the business’s prerequisites output and desired configuration.

{
  "ucp": {
    "payment_handlers": {
      "com.example.handler": [
        {
          "id": "processor_tokenizer_1234",
          "version": "2026-01-11",
          "spec": "https://example.com/ucp/handler",
          "schema": "https://example.com/ucp/handler/schema.json",
          "available_instruments": [
            // Instrument types this handler supports
          ],
          "config": {
            // Handler-specific configuration (see Config Shapes)
          }
        }
      ]
    }
  }
}

available_instruments is optional. When absent, the handler places no restrictions on instrument types or constraints — it supports the full set of instrument types defined by its handler schema. When present, it narrows the advertised types and/or applies additional constraints (e.g., limiting card brands to ["visa", "mastercard"]).

Handler Declaration Variants

The PaymentHandler schema defines three variants for different contexts. While only id and version are technically required, each variant serves a distinct purpose and typically includes different configuration:

Variant	Context	Purpose
business_schema	Business discovery (`/.well-known/ucp`)	Declares the business identity and how they’re configured for this handler. Contains merchant-specific settings.
platform_schema	Platform profile (advertised URI)	Declares the platform identity and how it supports this handler. Includes `spec` and `schema` URLs for implementers.
response_schema	Checkout/Order API responses	Runtime configuration with resolved context: merchant identity, resolved `available_instruments` for this checkout, tokenization specs, and other state needed to process the transaction. Platforms MUST treat this as authoritative.

Business Schema Example (business declares handler configuration):

{
  "id": "processor_tokenizer_1234",
  "version": "2026-01-11",
  "spec": "https://example.com/ucp/handler",
  "schema": "https://example.com/ucp/handler/schema.json",
  "available_instruments": [
    {
      "type": "card",
      "constraints": {
        "brands": ["visa", "mastercard"]
      }
    }
  ],
  "config": {
    "environment": "production",
    "business_id": "business_xyz_789"
  }
}

Platform Schema Example (platform declares handler support):

{
  "id": "platform_tokenizer_2345",
  "version": "2026-01-11",
  "spec": "https://example.com/ucp/handler",
  "schema": "https://example.com/ucp/handler/schema.json",
  "available_instruments": [
    {
      "type": "card",
      "constraints": {
        "brands": ["visa", "mastercard", "amex", "discover"]
      }
    }
  ],
  "config": {
    "environment": "production",
    "platform_id": "platform_abc_123"
  }
}

Response Schema Example (runtime context for checkout):

{
  "id": "processor_tokenizer_1234",
  "version": "2026-01-11",
  "available_instruments": [
    {
      "type": "card",
      "constraints": {
        "brands": ["visa", "mastercard"]
      }
    }
  ],
  "config": {
    "api_version": 2,
    "environment": "production",
    "business_id": "business_xyz_789"
  }
}

Resolving `available_instruments`

Both the platform and the business independently advertise available_instruments in their profiles. The business is responsible for resolving these into the authoritative value returned in the response_schema.

Resolution flow:

Platform declares capabilities — the platform’s profile includes available_instruments on each handler declaration. This tells the business what the platform can handle (e.g., it only supports ["visa", "mastercard", "amex", "discover"]).
Business resolves — upon receiving a request, the business computes the resolved available_instruments for the checkout by intersecting:
- The platform’s advertised available_instruments (its capabilities)
- Its own business_schema declaration (what the merchant is actually set up to accept)
- Cart/checkout context (e.g., certain item types may restrict eligible methods)
Response is authoritative — the available_instruments in the response_schema reflects the business’s resolved selection for this specific checkout. Platforms MUST treat it as authoritative and MUST NOT attempt to use instrument types or apply constraints that contradict it.

Example:

Source	`available_instruments`
Platform profile	`[{type: "card", constraints: {brands: ["visa", "mastercard", "amex", "discover"]}}]`
Business profile	`[{type: "card", constraints: {brands: ["visa", "mastercard", "amex"]}}]`
Response (resolved)	`[{type: "card", constraints: {brands: ["visa", "mastercard", "amex"]}}]`

In this example, the business’s PSP is not configured for Discover, so Discover is excluded from the response even though the platform supports it.

Defining the Schema

The schema field points to a JSON schema that defines handler-specific shapes. Authors typically define each shape in its own file and reference them:

Config — Configuration for platform/business declarations and runtime responses
Instrument — The payment instrument structure returned to platforms
Credential — The credential structure within instruments

Config Shapes

Each variant has its own config schema tailored to its context:

Variant	Config File	Purpose
business_schema	`types/business_config.json`	Business identity and merchant-specific settings
platform_schema	`types/platform_config.json`	Platform identity and platform-level settings
response_schema	`types/response_config.json`	Full runtime state: identities, tokenization specs

Instrument Shapes

Base Instrument Schemas:

Schema	Description
`payment_instrument.json`	Base: id, handler_id, type, billing_address, credential, display
`card_payment_instrument.json`	Extends base with display: brand, last_digits, expiry, card art

UCP provides base schemas for universal payment instruments like card. Spec authors MAY extend any of the base instruments to add handler-specific display data or customize the credential reference. Handlers MAY define multiple instrument types for different payment flows.

Credential Shapes

Base Credential Schemas:

Schema	Description
`payment_credential.json`	Base: type discriminator only
`token_credential.json`	Token: type + token string

UCP provides base schemas for universal payment credentials. Authors MAY extend these schemas to include handler-specific credential context. Handlers MAY define multiple credential types for different instrument flows.

The specification MUST define which credential types are accepted by the handler.

Important: If using token credentials, the schema MUST include an expiration field (expiry, ttl, or similar) to ensure platforms know when to refresh credentials.

Instrument Acquisition

Definition: The protocol a platform follows to acquire a payment instrument that can be submitted to the business’s checkout.

Signature:

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

Field	Description
`platform_prerequisites_output`	platform’s prerequisites output (config), if prerequisites were required
`handler_declaration.config`	Handler-specific configuration from the business
`binding`	Context for binding the credential to a specific checkout
`buyer_input`	Buyer’s payment selection or credentials
`checkout_instrument`	The payment instrument to submit at checkout

Processing

Definition: The steps a participant (typically business or PSP) takes to process a received payment instrument and complete the transaction.

Signature:

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

Field	Description
`identity`	The processing participant’s `PaymentIdentity`
`checkout_instrument`	The instrument received from the platform
`binding`	The binding context for verification
`transaction_context`	Checkout totals, line items, etc.
`processing_result`	Success/failure with payment details

Error Handling

The specification MUST define a mapping for common failures (e.g., ‘Declined’, ‘Insufficient Funds’, ‘Network Error’) to standard UCP Error definitions. This ensures the platform can render localized, consistent error messages to the buyer regardless of the underlying processor.

Key Definitions

Term	Definition
Binding	A cryptographic or logical association of a payment instrument to a specific checkout transaction and business identity. This prevents replay attacks where a valid credential intended for Business A is intercepted and used at Business B.

Specification Template

Handler specifications SHOULD use the standard template structure. Sections marked [REQUIRED] MUST be present; sections marked [CONDITIONAL] are required only when applicable.

→ Payment Handler Template

Conformance Checklist for Spec Authors

Before publishing a payment handler specification, verify:

Structure

Uses the standard template structure
All [REQUIRED] sections are present
[CONDITIONAL] sections are present when applicable

Participants

All participants are listed
Each participant’s role is clearly described
Note on “Business” vs “Merchant” terminology added if applicable

Prerequisites

Prerequisites process is documented for each participant that requires it
Onboarding inputs are specified
Prerequisites output is described (identity + any additional config)
Identity maps to PaymentIdentity structure (access_token)

Handler Declaration

Identity schema is documented (base or extended)
Configuration schema is documented (if applicable) and includes environment
Instrument schema is documented (base or extended)

Instrument Acquisition

Protocol steps are enumerated and clear
Logical flow is mapped to actual protocol
API calls or SDK usage is shown with examples
Binding requirements are specified
Checkout Payment Instrument creation and shape is well-defined

Processing

Processing steps are enumerated and clear
Verification requirements are specified
Error handling and mapping is addressed

Security

Security requirements are listed
Binding verification is required
Credential handling guidance is provided
Token expiry is defined (if applicable)

General

Handler name follows reverse-DNS convention
Version follows YYYY-MM-DD format
All schema URLs match namespace authority
References section includes all schemas

Best Practices

Follow these guidelines to create high-quality, maintainable handler specifications:

Schema Design

Practice	Description
Extend, don’t reinvent	Use `allOf` to compose base schemas. Don’t redefine `brand`, `last_digits`, etc.
Use const for discriminators	Define `credential.type` as a `const` to identify credential types unambiguously.
Validate early	Publish schemas at stable URLs before finalizing the spec so implementers can validate.
Include Expiry	When designing token credentials, always include `expiry` or `ttl`.

Documentation

Practice	Description
Show, don’t just tell	Include complete JSON examples for every schema and protocol step.
Document error cases	Specify what errors can occur and how participants should handle them.
Version independently	The handler version evolves independently of UCP core versions.

Security

Practice	Description
Require binding	Always tie credentials to a specific checkout via `binding`.
Minimize credential exposure	Design flows so raw credentials (PANs, etc.) touch as few systems as possible.
Specify token lifetimes	Document whether tokens are single-use, time-limited, or session-scoped.

Maintainability

Practice	Description
Host schemas at stable URLs	Schema URLs should not change; use versioned paths if needed.
Fail gracefully	Define clear error responses for common failure scenarios.
Link to examples	Reference existing handler specs and the Tokenization Guide for common flows.

Payment Handler Specification Guide

Payment Handler Specification Guide

Introduction

Purpose

Scope

Core Concepts

Participants

Prerequisites

Handler Declaration

Handler Declaration Variants

Resolving available_instruments

Defining the Schema

Config Shapes

Instrument Shapes

Credential Shapes

Instrument Acquisition

Processing

Error Handling

Key Definitions

Specification Template

Conformance Checklist for Spec Authors

Structure

Participants

Prerequisites

Handler Declaration

Instrument Acquisition

Processing

Security

General

Best Practices

Schema Design

Documentation

Security

Maintainability

See Also

Resolving `available_instruments`