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

[raginpirate]

👋 Hey @jamesandersen thanks for the PR!

I want to level-set, since I think there's a bit of a disconnect in your summary of the issue vs. some of your deeper discussion points.

However, there is no support for card network tokens

We do already have network tokens represented on the base card credential: https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/shopping/types/card_credential.json
We take a similar approach as many processor APIs and agentic commerce specs which have defined this as a unified credential type instead of separating them.

From my POV this intersects nearly 1-1 with your proposed network token credential, with the exception being that the TRID is not on that schema, because TRIDs are not required for processing.

What I do love from this conversation is that it engages with our current documentation and perhaps some incorrect edges around PCI. Do you see an opportunity for us to improve our messaging about how to use the tokenization handler guide, or how to avoid making platforms or businesses think they MUST have PCI compliance to jump into using our current schemas? I would love to steer this PR in that direction instead, which I think I see some hints as buried in your PR comment :)

[jamesandersen]

Thanks @raginpirate! I appreciate you taking the time to walk through this. You're right — I initially missed the card_number_type discriminator on card_credential.json, and not seeing a dedicated network token schema, I went ahead and proposed one as a new type. Having looked more carefully, the existing unified credential covers the core use case well.

I'd like to pivot this PR to two concrete changes:

1. Add token_requestor_id to card_credential.json

The one field I think is worth adding to the existing schema. The TRID is assigned by card networks (Visa VTS, Mastercard MDES) to each enrolled token requestor — it identifies who provisioned a given network token. This matters in platform commerce scenarios where the entity presenting the token at checkout differs from the entity that originally provisioned it (e.g., a platform holds tokens under its own TRID but submits them through a merchant's PSP). Braintree includes it as an optional field in their network_tokenization_attributes for third-party card-on-file token transactions.

2. Documentation improvements for network token usage and PCI scope

The tokenization guide does a great job covering the FPAN → token flow, but doesn't address the pre-provisioned network token path — where a platform already holds a network token and presents it directly at checkout without a tokenize/detokenize round-trip. I'd propose adding:

• A section in the tokenization guide covering network tokens as source credentials, showing how card_number_type: "network_token" + cryptogram/eci_value signals a pre-provisioned token flow that bypasses the tokenize/detokenize lifecycle
• Clearer language in the card credential schema description about reduced PCI DSS scope when using network tokens vs FPANs — specifically that platforms presenting DPANs with cryptograms operate under a different compliance posture than those handling raw PANs
• A usage example showing a card_number_type: "network_token" credential alongside the existing FPAN examples

Happy to rework this PR or start fresh — which do you prefer?

[kmcduffie]

Hey @jamesandersen! A few questions on #1 above.

1. token_requestor_id
   I wanted to ask a few questions to clarify the request. For the TRID, am I understanding correctly, that this ID would be passed to the network when requesting a token? Or is it something that is returned with the token? Since the TRID is an identifier for the requester, would it make sense for the TRID to be part of the merchant configuration?

[jamesandersen]

@kmcduffie As I understand it, in the most common flow — where the handler's PSP provisioned the token — the PSP already knows the TRID and attaches it to the authorization automatically. I'd guess that why most PSP APIs treat it as optional; the merchant never needs to provide it.

Where I think it becomes relevant is "Bring Your Own Token" (BYOT) scenarios — where the entity that provisioned the token differs from the entity presenting it for authorization. IIUC this would be the primary use case of card_number_type: "network_token" i.e. the platform wants to send provisioned network tokens to the business where ultimately the business's PSP will use them for payment e.g. Braintree BYOT flow

For that reason I think the TRID fits best on the credential rather than merchant config because in the BYOT case, the merchant may not know or own the TRID — it belongs to whoever provisioned the token i.e. the platform in UCP framing.

[kmcduffie]

@jamesandersen Thanks for the reference to the Braintree APIs. I see that the field is optional. Do you know how that field is used by PSPs?

[jamesandersen]

@kmcduffie I've been digging a bit to better understand myself; this gets a little beyond my day to day context...

My understanding is that the TRID is needed in the authorization message itself — not just at cryptogram generation time — for cryptogram validation. Since the cryptogram output is a binary blob that doesn't identify which token requestor generated it, at authorization time, the network needs the TRID as a separate field to look up the correct cryptographic keys and validate the cryptogram, check transaction counters, etc. against the right token requestor's provisioning record.

I think downstream at the issuer they may have trust profiles for different TRIDs but by that time the network would be able to provide the TRID.

In the UCP context I'm still primarily imagining use of card_number_type: "network_token" would be for BYOT cases so the businesses PSP may need the TRID to populate the correct authorization message fields — without it, the network may decline or treat it as a non-token transaction.

[raginpirate]

1. Add token_requestor_id to card_credential.json

I you have a business case that requires it, I don't see a reason to block this optional field from the spec. But as @kmcduffie is poking at, I wasn't able to confirm a normal reason that processors (or businesses in front of them) are trying to handle that value ahead of it reaching the network. For example, agentic network tokens leaning on the cvv to proxy the cryptogram, would certainly not leverage TRID as an external data point.

2. Documentation improvements for network token usage and PCI scope

Yeah I would love to see your iteration on this 😄 I think your proposals make sense and I am very happy to see more clear documentation about when / why PCI intersects with UCP 🚀

Probably nice to close this PR and open one with a more targeted title and referencing this to preserve history, but thats up to you!

[jamesandersen]

@raginpirate good comments above. For #1 - we may be straying into the theoretical on whether TRID is needed for a BYOT scenario (only have Braintree docs as a more concrete support). I may have some more tangible experience to bring to this in a few months. For now, I'm content just dropping the TRID property

I'll follow your suggestion and open a hopefully more straightforward PR for a couple docs clarifications ... but a bit later (it's late!)