feat: add card network token credential and instrument types

[jamesandersen]

Enhancement Proposal: Card Network Token Credential Type

Summary

A new card_network_token credential type for UCP that enables platforms to present card network tokens (Visa VTS, Mastercard MDES, Amex Token Service) directly as payment credentials in checkout sessions — without requiring re-tokenization through a handler or falling back to raw PANs.

Motivation

UCP currently supports payment tokenization through handler-specific tokens and a delegated payment model. However, there is no support for card network tokens — tokenized card credentials issued by card networks that replace the primary account number (PAN) with a network-level token.

Card network tokens are an industry-standard payment security mechanism with broad PSP acceptance. Every major processor supports directly processing network tokens with the same core fields (token/DPAN, cryptogram, ECI):

PSP	Always Required	Conditional / Optional	Documentation
Adyen	DPAN, expiry, cardholder name, cryptogram, ECI	Brand (co-badged cards), CVC	Network Tokenization
Chase	Token, expiry	Cryptogram + ECI (may be omitted for MIT/recurring)	Online Payments
Braintree	DPAN, expiry, cryptogram (for CIT)	ECI, token requestor ID, transaction source (for MIT)	Bring Your Own Token
Stripe	Card data, cryptogram + ECI	Network, 3DS version	PCI required for API docs
Cybersource	Token, cryptogram, ECI, expiry	—	Auth with NT

UCP's own specification explicitly identifies network tokens as a mechanism for platforms to avoid PCI-DSS scope:

"Platforms can avoid PCI-DSS scope by using handlers providing opaque credentials, never accessing raw payment data."
— UCP Specification Overview: Credential Flow & PCI Scope

Yet despite this design intent, UCP currently has no dedicated credential type for network tokens. Platforms that already hold card network tokens cannot use them directly.

Token Provisioning

Platforms can obtain card network tokens through several standard provisioning channels:

• Direct network integration — Platform enrolls as a Token Requestor with Visa VTS, Mastercard MDES, or Amex Token Service
• PSP-managed tokenization — Platform's PSP manages token lifecycle on behalf of the platform
• Secure Remote Commerce (SRC) — EMVCo's SRC specification ("Click to Pay") maintains a directory of tokenized cards across participating networks

Goals

• Enable platforms holding card network tokens to present them directly as UCP payment credentials
• Support all major card networks (Visa, Mastercard, Amex, Discover, JCB)
• Reflect PSP field requirements accurately (required vs. conditional vs. optional)
• Follow UCP's existing credential and instrument composition patterns (allOf with base schemas)
• Prevent sensitive data leakage in API responses via ucp_response: "omit"

Non-Goals

• Replacing or modifying the existing card_credential.json schema
• Token provisioning or lifecycle management (out of scope — handled by the card network)
• Defining how merchants/PSPs should process network tokens (PSP-specific)
• Defining a new tokenization handler — network tokens are pre-provisioned credentials, not produced by the tokenize/detokenize flow

Related Work

• The current card_credential.json includes partial network token support via card_number_type: "network_token" with cryptogram and eci_value fields. See "Discussion Points" below for why a separate credential type is proposed.
• card_payment_instrument.json — defines the card instrument with display properties and the available_card_payment_instrument variant with constraints.brands.
• token_credential.json — base token credential with ucp_response: "omit" pattern on token field.
• Tokenization Guide — defines the tokenize/detokenize flow for handler-produced tokens. Network tokens bypass this flow.
• Payment Handler Guide — defines handler declaration, instrument acquisition, and processing patterns.
• PR #187 (merged): Added available_instruments with constraints.
• PR #214 (merged): Added payment instrument qualifiers.

Detailed Design

Credential Schema: card_network_token_credential.json

The credential extends payment_credential.json via allOf:

Field	Type	Required	Description
type	const	Yes	"card_network_token"
token	string	Yes	Card network token value (DPAN). Omitted from responses.
token_expiry_month	integer	Yes	Month of the token's expiration date (1-12)
token_expiry_year	integer	Yes	Year of the token's expiration date
cryptogram	string	No	One-time-use cryptogram (TAVV/CAVV). Omitted from responses.
eci_value	string	No	Electronic Commerce Indicator / Security Level Indicator
name	string	No	Cardholder name. Required by some PSPs (e.g., Adyen).
token_requestor_id	string	No	Token Requestor ID (TRID) from the card network

Instrument Schema: card_network_token_instrument.json

Network tokens are cards — they share display properties (brand, last digits, expiry, card art) with card instruments. The instrument extends card_payment_instrument.json and includes an available_* variant following the established pattern:

• Inherits card display properties (brand, last_digits, expiry_month, expiry_year, card_art)
• Defines available_card_network_token_instrument extending available_card_payment_instrument to inherit constraints.brands
• Pairs with card_network_token_credential.json via the credential property

How Network Tokens Fit the Handler Model

Network tokens are pre-provisioned credentials that bypass the tokenize/detokenize flow:

1. Negotiation — The business's handler declares available_instruments including card_network_token.
2. Acquisition — No tokenizer round-trip is needed. The platform constructs the instrument from a pre-provisioned network token, including a fresh cryptogram from the card network.
3. Completion — The platform submits the card_network_token instrument. The business's PSP processes the network token directly.

This is analogous to how wallet handlers (e.g., Google Pay, Shop Pay) work: the platform holds a pre-provisioned opaque credential and presents it directly.

Relationship to Existing card_credential.json

The current card_credential.json includes partial network token support via card_number_type: "network_token". However, that schema carries PCI restrictions that apply to the entire schema:

• "This credential type MUST NOT be used for checkout, only with payment handlers that tokenize or encrypt credentials."
• "Both parties handling CardCredential MUST be PCI DSS compliant."

A separate credential type is proposed because:

1. PCI scope — The blanket PCI requirement exists because the schema handles raw PANs. Network tokens reduce PCI DSS compliance scope compared to handling raw card data.
2. Missing fields — card_credential.json lacks token_requestor_id and has no way to distinguish token expiry from card expiry (network tokens have independent expiry dates).
3. No instrument schema — there is no instrument type for network tokens paired with a reduced-PCI-scope credential.
4. Semantic clarity — presenting a network token as a card_credential implies the platform holds PCI-scoped card data when it does not.

Alternative approach: The community could choose to enhance card_credential.json with the missing fields and relax the PCI restriction when card_number_type is "network_token". Either approach achieves the same functional goal. This is an explicit discussion point.

Usage Example

A platform presenting a pre-provisioned Visa network token at checkout:

{
  "payment": {
    "instruments": [
      {
        "id": "pi_ntoken_001",
        "handler_id": "handler_merchant_psp",
        "type": "card_network_token",
        "credential": {
          "type": "card_network_token",
          "token": "4895370012003478",
          "token_expiry_month": 12,
          "token_expiry_year": 2028,
          "name": "Jane Doe",
          "cryptogram": "AJkBBkhAAAAA0YFAAAAAAAAAAA==",
          "eci_value": "05",
          "token_requestor_id": "40012345678"
        },
        "display": {
          "brand": "visa",
          "last_digits": "3478",
          "expiry_month": 12,
          "expiry_year": 2028
        },
        "selected": true
      }
    ]
  }
}

Design Rationale

1. Follows UCP's composition patterns — credential extends payment_credential.json via allOf; instrument extends card_payment_instrument.json to inherit display properties and available_* variant pattern.
2. Required vs optional fields reflect PSP reality — token and token_expiry are universally required by all PSPs. Network/brand is inherited from card_payment_instrument.json. Cryptogram and eci_value are optional because they are conditional (CIT vs MIT). Name is optional (only Adyen requires it).
3. Cryptogram and token use ucp_response: omit — prevents leaking sensitive data in API responses, following the pattern from token_credential.json.
4. Token Requestor ID — optional; important in agentic flows where the token presenter differs from the provisioner.
5. Pre-provisioned credential model — network tokens bypass the tokenize/detokenize flow, analogous to wallet handlers.
6. Eliminates CVV collection — the cryptogram structurally replaces CVC, removing the need for platforms to collect CVV.
7. Aligns with UCP's stated PCI design — the specification overview identifies network tokens as opaque credentials that reduce compliance scope. A dedicated credential type realizes this design intent.

Risks and Mitigations

Risk	Mitigation
Overlap with existing card_credential.json network token support	Proposal explicitly acknowledges the alternative of enhancing card_credential.json and presents this as a discussion point for the TC.
PCI scope confusion	Network tokens reduce PCI DSS compliance scope compared to handling raw card data. UCP's own specification states that platforms working with network tokens can reduce compliance overhead.
PSP-specific field variations	Schema uses required fields only where universally needed; optional fields cover PSP-specific requirements.
Sensitive data in responses	ucp_response: "omit" on token and cryptogram fields prevents leakage.

Test Plan

• JSON Schema validation: validate usage example against the schema
• Composition test: verify allOf with payment_credential.json produces valid combined schema
• Required field enforcement: verify rejection when token or expiry fields are missing
• Response omission: verify token and cryptogram are omitted from API responses
• PSP compatibility: verify schema accommodates all five documented PSP field sets

Graduation Criteria

• Schema merged into UCP source
• Specification documentation complete
• 2+ independent implementations
• TC majority vote for Candidate status

Code Changes

New Files:

• source/schemas/shopping/types/card_network_token_credential.json — credential schema
• source/schemas/shopping/types/card_network_token_instrument.json — instrument schema with available_card_network_token_instrument variant
• docs/specification/card-network-token.md — documentation

Modified Files:

• mkdocs.yml — Added card network token to nav and llmstxt sections
• .cspell/custom-words.txt — Added network token-related terms

Note: No modifications to existing schemas required. Base payment_credential.json uses additionalProperties: true; card_payment_instrument.json is extended via allOf, not modified.

Discussion Points

• New credential type vs. enhancing card_credential.json with conditional PCI relaxation?
• Should available_card_network_token_instrument extend available_card_payment_instrument (inheriting constraints.brands) or define its own constraints?

References

• EMVCo Token Framework
• EMVCo Secure Remote Commerce (SRC)
• Visa Token Service
• Mastercard MDES
• Adyen Network Tokens
• Braintree Bring Your Own Token
• Chase Online Payments Tokenization
• UCP Specification Overview: Credential Flow & PCI Scope
• UCP Payment Handler Guide
• UCP Tokenization Guide
• UCP payment_credential.json — base credential schema
• UCP card_credential.json — existing card credential with partial network token support
• UCP card_payment_instrument.json — card instrument with display properties and available_card_payment_instrument variant

---

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings