How UCP Handles Payment Tokenization and Credential Flows

Universal Commerce Protocol (UCP) exchanges raw payment credentials for cryptographically random, opaque tokens bound to specific checkout sessions via the /tokenize and /detokenize endpoints defined in source/handlers/tokenization/openapi.json.

Universal Commerce Protocol (UCP) provides a standardized approach to payment tokenization and credential flows that eliminates the need for merchants to handle sensitive payment data repeatedly. By implementing strict binding requirements and mandatory API contracts, the protocol ensures that tokens are cryptographically secure, session-scoped, and non-reversible according to the specifications in [docs/specification/tokenization-guide.md](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/tokenization-guide.md).

Core Architecture Components

UCP’s tokenization system relies on five key components defined in the protocol schemas and OpenAPI specifications.

Tokenization API

The Tokenization API exposes standardized /tokenize and /detokenize endpoints that all payment handlers must implement, as specified in [source/handlers/tokenization/openapi.json](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/handlers/tokenization/openapi.json). These endpoints handle the conversion between raw payment credentials and opaque tokens, enforcing uniform request and response formats across all implementations.

Binding Object

Every tokenization request requires a binding object that couples the token to a specific checkout_id and optionally a participant identity. This prevents token reuse across sessions or actors. The structure is defined in [source/schemas/shopping/types/binding.json](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/shopping/types/binding.json), which mandates that handlers verify the binding matches the caller’s authenticated identity before processing.

Payment Credential Schema

The Payment Credential Schema in [source/schemas/shopping/types/payment_credential.json](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/shopping/types/payment_credential.json) describes the shape of raw credentials supplied to /tokenize. This extensible schema supports custom payment types while maintaining strict validation rules for standard fields like card numbers and expiry dates.

Token Credential

The token credential returned by the /tokenize call is an opaque, non-reversible identifier generated using a cryptographically secure random number generator with ≥ 128 bits of entropy. As implemented in UCP, these tokens never contain embedded credential data and are scoped specifically to the issuing tokenizer.

Token Lifecycle Policies

Handlers declare Token Lifecycle Policies that determine whether tokens are single-use, TTL-based, or session-scoped. While the protocol does not prescribe specific storage mechanisms, implementations must enforce their declared policies using secure vaults, HSMs, or encrypted caches as documented in the tokenization guide.

Tokenization Flow

The tokenization process follows a strict four-step sequence to ensure security and traceability.

1. Request Preparation: The caller constructs a payload containing a credential object and a binding that identifies the checkout session and target identity.

2. Binding Validation: The handler validates that the binding matches the caller’s authenticated identity when an identity field is present, preventing unauthorized tokenization.

3. Token Generation: The handler creates a token using a cryptographically secure random generator and stores the association between token, credential, and binding.

4. Token Return: The handler returns the opaque token, which can now be used in checkout flows without exposing raw credentials.

The OpenAPI contract requires the following request structure:

{
  "credential": { /* any payment_credential */ },
  "binding": {
    "checkout_id": "abc123",
    "identity": { "access_token": "merchant_001" }
  }
}

Python Example: Tokenizing a Card

import requests

url = "https://api.example.com/ucp/tokenize"
payload = {
    "credential": {
        "type": "card",
        "card_number_type": "fpan",
        "number": "4111111111111111",
        "expiry_month": 12,
        "expiry_year": 2026,
        "cvc": "123",
        "name": "Jane Doe"
    },
    "binding": {
        "checkout_id": "checkout_01",
        "identity": {
            "access_token": "merchant_abc123"
        }
    }
}
headers = {"Content-Type": "application/json"}

resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
print("Token:", resp.json()["token"])

Detokenization Flow

When downstream services require the original credential—for example, to submit to an acquiring bank—they invoke the /detokenize endpoint with the token and the original binding. The handler verifies that the provided binding matches the stored record before releasing the credential, protecting against token theft and replay attacks.

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

If the checkout_id or identity does not match the tokenization-time values, the handler must reject the request with an authorization error.

Python Example: Detokenizing

import requests

url = "https://api.example.com/ucp/detokenize"
payload = {
    "token": "tok_abc123xyz789",
    "binding": {
        "checkout_id": "checkout_01"
    }
}
headers = {"Content-Type": "application/json"}

resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
credential = resp.json()
print("Original credential:", credential)

Security Guarantees

UCP enforces six critical security requirements for all tokenization handlers:

• Mandatory Binding: Every request requires a checkout_id and identity verification when applicable, ensuring tokens are session-bound.
• Binding Verification: Handlers must compare incoming bindings against stored records before any token operation.
• Cryptographic Randomness: Token generation must use secure RNG with minimum 128-bit entropy.
• Non-Reversible Tokens: Tokens are opaque identifiers without embedded credential data.
• Lifecycle Enforcement: Handlers must implement declared TTL or single-use invalidation policies.
• Transport Security: All API calls must use TLS with authentication mechanisms such as OAuth 2.0 as defined per handler specification.

Extensibility

UCP supports two primary extension mechanisms for specialized payment scenarios.

Custom Credential Types

Handlers may extend [source/schemas/shopping/types/payment_credential.json](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/shopping/types/payment_credential.json) with additional properties to support alternative payment methods while maintaining compliance with the base tokenization contract.

Encrypted Credential Alternatives

For implementations requiring end-to-end encryption rather than tokenization, handlers can replace the standard flow with encrypted credential handlers that still adhere to the binding contract. This pattern allows sensitive data to remain encrypted throughout the transaction while maintaining session isolation.

Summary

• UCP standardizes payment tokenization through mandatory /tokenize and /detokenize endpoints defined in source/handlers/tokenization/openapi.json.
• The binding object ties every token to a specific checkout_id and participant identity, preventing cross-session reuse.
• Tokens must be cryptographically random with ≥ 128 bits of entropy and completely opaque.
• Handlers validate bindings during both tokenization and detokenization to prevent unauthorized credential retrieval.
• The protocol supports extensible credential types and alternative encryption patterns while maintaining strict security guarantees.

Frequently Asked Questions

How does UCP prevent token reuse across different checkout sessions?

UCP mandates that every tokenization request include a binding object containing a checkout_id. Handlers store this binding alongside the token and verify it during detokenization. If the checkout_id in a detokenization request does not match the original, the handler rejects the request, effectively preventing token theft and replay attacks across sessions.

What are the specific entropy requirements for UCP tokens?

According to the UCP tokenization specification, handlers must generate tokens using a cryptographically secure random number generator with at least 128 bits of entropy. This requirement ensures that tokens cannot be predicted or brute-forced, maintaining the security of the credential mapping.

Can merchants tokenize custom payment methods beyond standard cards?

Yes. The Payment Credential Schema in source/schemas/shopping/types/payment_credential.json is extensible, allowing handlers to define custom credential types for alternative payment methods. As long as the handler implements the required /tokenize and /detokenize endpoints and adheres to the binding contract, the protocol supports any payment instrument that can be described in JSON schema.

What happens if the binding object does not match during detokenization?

When a detokenization request arrives, the handler compares the provided binding against the stored record associated with the token. If the checkout_id or identity values mismatch—indicating a potential replay attack or unauthorized access—the handler must return an authorization error (typically HTTP 403 Forbidden) and must not release the original credential.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}