Tokenization Guide

Overview

This guide is for implementers building tokenization payment handlers, defining the shared API, security requirements, and conformance criteria.

Core Concepts

Credential Flow

Tokenization handlers transform credentials between source and checkout forms:

Platform has:            Tokenizer            Business receives:
Card Credential    ──▶  /tokenize  ──▶         TokenCredential
(FPAN/DPAN)                                   (Token)

Token Lifecycle

Policy	Description	Use Case
Single-use	Invalidated after first detokenization	Most secure; recommended
TTL-based	Expires after fixed duration (e.g., 15 min)	Allows retries
Session-scoped	Valid for checkout session duration	Complex flows

Binding

All tokenization requests require a binding object:

Field	Required	Description
`checkout_id`	Yes	The checkout session this token is valid for
`identity`	Conditional	Participant identity to bind to

OpenAPI

POST /tokenize

Converts a raw credential into a token bound to a checkout and identity.

Request:

POST /tokenize
Content-Type: application/json

{
  "credential": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4111111111111111",
    "expiry_month": 12,
    "expiry_year": 2026,
    "cvc": "123"
  },
  "binding": {
    "checkout_id": "abc123",
    "identity": {
      "access_token": "merchant_001"
    }
  }
}

Response:

{
  "token": "tok_abc123xyz789"
}

POST /detokenize

Returns the original credential for a valid token. Binding must match.

Request:

POST /detokenize
Content-Type: application/json
Authorization: Bearer {caller_access_token}

{
  "token": "tok_abc123xyz789",
  "binding": {
    "checkout_id": "abc123"
  }
}

Response:

{
  "type": "card",
  "card_number_type": "fpan",
  "number": "4111111111111111",
  "expiry_month": 12,
  "expiry_year": 2026,
  "cvc": "123"
}

Security Requirements

Requirement	Description
Binding required	Credentials MUST be bound to `checkout_id` and `identity`
Binding verified	Tokenizer MUST verify binding matches before returning credentials
Cryptographically random	Use secure random generators; tokens must be unguessable
Sufficient length	Minimum 128 bits of entropy
Non-reversible	Cannot derive the credential from the token
Time-limited	Enforce TTL appropriate to use case (typically 5-30 minutes)
Single-use preferred	Invalidate after first detokenization when possible

Handler Specification Requirements

When publishing your handler, your specification MUST include:

Requirement	Example
Unique handler name	`com.example.tokenization_payment`
Endpoint URLs	Production and sandbox base URLs
Authentication requirements	OAuth 2.0, API keys, etc.
Onboarding process	How participants register and receive identities
Accepted credentials	Which credential types are accepted
Token lifecycle policy	Single-use, TTL, or session-scoped

Conformance Checklist

A tokenizer handler conforms if it:

Publishes handler specification at stable URL with unique name
Implements /tokenize and/or /detokenize per OpenAPI
Defines authentication and onboarding requirements
Documents credential transformation between source and checkout forms
Produces tokens compatible with TokenCredential schema
Specifies token lifecycle policy
Requires binding with checkout_id on tokenization requests
Verifies binding matches on detokenization requests

References

Resource	URL
Tokenization OpenAPI	`https://ucp.dev/handlers/tokenization/openapi.json`
Identity Schema	`https://ucp.dev/schemas/shopping/types/payment_identity.json`
Binding Schema	`https://ucp.dev/schemas/shopping/types/binding.json`
Token Credential Schema	`https://ucp.dev/schemas/shopping/types/token_credential.json`