Processor Tokenizer Payment Handler

• Handler Name: com.example.processor_tokenizer
• Type: Payment Handler Example

Introduction

This handler implements a "Tokenize to Process" flow where the entity that generates the token (the Tokenizer) is the same entity that processes the final payment (the Processor).

Note: While this example uses card credentials, the pattern applies to any credential type. Compliance requirements vary by credential type (e.g., PCI DSS for cards).

This specification unifies two common implementation scenarios:

1. Business-Hosted: An enterprise Business hosts their own secure vault. The Business tokenizes and processes.
2. PSP-Hosted: The Business uses a third-party PSP. The PSP tokenizes and processes.

In both cases, no API detokenization step is required. The token resolution happens internally within the Processor's secure environment.

Comparison of Scenarios

Feature	Scenario A: PSP-Hosted	Scenario B: Business-Hosted
Tokenizer Host	Third-Party PSP	The Business
Compliance Scope	Low (Business never sees PAN)	High (Business stores PAN)
Identity Binding	Required (PSP needs Merchant Identifier)	Implicit (Business knows itself)

---

Participants

Participant	Role	Prerequisites
Tokenizer / Processor	Host /tokenize endpoint, store tokens, process payments. (Can be Business or PSP).	Compliance per credential type (e.g., PCI DSS for cards).
Platform	Collect credentials via secure credential provider, call Tokenizer, submit checkout.	Secure credential provider.
Business	Configures the handler for the checkout.	None (if PSP-hosted).

Pattern Flow

+------------+                         +-----------------------------------+
|  Platform  |                         |       Tokenizer / Processor       |
| (Collector)|                         |      (Business or PSP)            |
+-----+------+                         +-----------------+-----------------+
      |                                                  |
      |  1. GET ucp.payment_handlers                     |
      |------------------------------------------------->|
      |                                                  |
      |  2. Handler Config (URL + Identity)              |
      |<-------------------------------------------------|
      |                                                  |
      |  3. POST /tokenize (Credential + Identity)       |
      |------------------------------------------------->|
      |                                                  |
      |  4. Token                                        |
      |<-------------------------------------------------|
      |                                                  |
      |  5. POST checkout with TokenCredential           |
      |------------------------------------------------->|
      |                                                  |
      |        (Internal Resolution: Token -> Info)      |
      |                                                  |
      |  6. Payment Result                               |
      |<-------------------------------------------------|

---

Configuration

The Business advertises this handler in their UCP profile's payment_handlers registry. The configuration determines whether the Platform acts in "PSP Mode" (sending identity) or "Direct Mode" (implicit identity).

Business Config (Discovery)

The business advertises their tokenization endpoint and identity during discovery. The handler's specification (referenced via the spec field) documents the /tokenize endpoint URL.

Field	Type	Required	Description
environment	string	Yes	API environment (sandbox or production)
business_id	string	Yes	Business identifier with the processor

Example Business Handler Declaration

{
  "ucp": {
    "version": "2026-08-25",
    "payment_handlers": {
      "com.example.processor_tokenizer": [
        {
          "id": "processor_tokenizer",
          "version": "2026-08-25",
          "spec": "https://example.com/ucp/processor-tokenizer.json",
          "schema": "https://example.com/ucp/processor-tokenizer/schema.json",
          "available_instruments": [
            {
              "type": "card",
              "constraints":