docs: clarify network token usage and PCI scope in card credentials by jamesandersen · Pull Request #367 · Universal-Commerce-Protocol/ucp

jamesandersen · 2026-04-17T07:05:20Z

Summary

Add a Pre-Provisioned Network Tokens section to the tokenization guide, documenting the BYOT path where platforms present card network tokens directly (card_number_type: "network_token") without a tokenize/detokenize round-trip
Clarify PCI scope differences between FPAN and network token credential modes in the overview and card credential schema description
Add a network token credential example with cryptogram and eci_value

Split from #296 into a focused docs-only PR per reviewer feedback. TRID intentionally omitted per discussion in #296.

Type of change

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
cspell passes (added MDES to custom dictionary)
markdownlint passes

Add documentation for pre-provisioned network token usage and PCI scope distinctions between FPAN and network token credential modes: - Add "Pre-Provisioned Network Tokens" section to the tokenization guide covering the BYOT path where platforms present card network tokens directly as card_number_type: "network_token" without a tokenize/detokenize round-trip - Add network token bullet to Platform PCI Scope in the overview - Update card_credential.json description to distinguish PCI scope between fpan (full PCI DSS) and network_token (reduced scope) References Universal-Commerce-Protocol#296 — split from the original card network token credential PR into a focused docs-only change per reviewer feedback.

kmcduffie · 2026-04-20T16:04:32Z

@jamesandersen At a high level I think this makes sense. At the same time, I would like to avoid setting the UCP documentation in a way that it needs to be updated if PCI guidance changes. Would you be open to adjusting the language to reference the PCI guidance and do the right thing?

Update three locations that asserted DPANs "are not considered cardholder data by most acquirers" to instead reference current PCI DSS guidance, avoiding scope claims that could go stale if PCI SSC updates requirements.

jamesandersen · 2026-04-21T05:49:39Z

@kmcduffie Good call — I was trying to find phrasing that didn't imply network tokens were not in scope of PCI DSS, but referring to the spec itself with guidance to consult it is a better path. Updated all three places where I made scope assertions (overview, tokenization guide, card_credential.json description) to point to current PCI DSS guidance instead. Pushing now.

kmcduffie

Sorry for some of the outdated comments, I couldn't figure out how to delete the no longer relevant ones.

kmcduffie · 2026-04-20T15:48:22Z

 - Using PSP tokenization payment handlers where raw credentials never pass
    through the platform
+- Presenting pre-provisioned card network tokens
+    (`card_number_type: "network_token"`) — DPANs with cryptograms are not


What do you think of having this cover both DPANs and CPANs?

kmcduffie · 2026-04-20T15:59:23Z

  "$id": "https://ucp.dev/schemas/shopping/types/card_credential.json",
  "title": "Card Credential",
-  "description": "A card credential containing sensitive payment card details including raw Primary Account Numbers (PANs). This credential type MUST NOT be used for checkout, only with payment handlers that tokenize or encrypt credentials. CRITICAL: Both parties handling CardCredential (sender and receiver) MUST be PCI DSS compliant. Transmission MUST use HTTPS/TLS with strong cipher suites.",
+  "description": "A card credential containing payment card details. When card_number_type is 'fpan', this contains a raw Primary Account Number (PAN) — both parties MUST be PCI DSS compliant. When card_number_type is 'network_token', this contains a Device PAN (DPAN) with cryptogram and ECI, which operates under reduced PCI scope as DPANs are not considered cardholder data by most acquirers. FPAN credentials MUST NOT be used directly for checkout — use payment handlers that tokenize or encrypt credentials. Transmission MUST use HTTPS/TLS with strong cipher suites.",


There is a situation where the card_number_type is fpan, but can be exchanged in a secure flow outside of UCP, where what is passed from the payment handler is effectively a foreign key to that value that was previously exchanged, or a reference to something that can be retrieved.

kmcduffie · 2026-04-20T16:00:09Z

+### Pre-Provisioned Network Tokens
+
+Not all credential flows require a tokenize/detokenize round-trip. When a
+platform already holds a **card network token** (provisioned via Visa VTS,


Given the new APIs networks are standing up, what do you think of dropping the API names and having the documentation simply reference Visa / MC?

nit: I would drop any concern about who provisioned it here to stay bias-free in the protocol documentation 😄

Agreed — dropped the VTS/MDES references.

kmcduffie · 2026-04-20T16:02:12Z

+
+```json
+{
+  "type": "card",


There is also a flow where this obj, even when DPAN / CPAN, could still be wrapped in a payment_handler wrapper. It wouldn't require a de-tokenization call to an out of band API, but would make the object opaque to any intermediate parties.

Can you update the language to be open to that setup as well? I would expect the object definition of the card credential would specify what the object contains.

Aligned and truthfully I think thats what would fit the current state of UCP!

Yep - language is updated to note a payment handler is needed for negotiation. This should leave the door open for handlers that also that wrap credentials for intermediary opacity.

I'm interested to discuss/learn more about pros/cons of wrapping vs. directly passing network tokens (which the schema seems to allow on a complete checkout call) BUT also interested in getting this PR over the finish line before diving into that further ;-)

kmcduffie · 2026-04-21T16:52:39Z

 - Using PSP tokenization payment handlers where raw credentials never pass
    through the platform
+- Presenting pre-provisioned card network tokens
+    (`card_number_type: "network_token"`) — DPANs with cryptograms may


With CPANs, not all cryptograms will be device bound. What do you think of updating the comments to be more broadly around cryptograms?

Good call — updated the language to say "network tokens with cryptograms" rather than "DPANs with cryptograms," so it covers both DPANs and CPANs without assuming device-binding.

raginpirate

Really appreciate you working on this @jamesandersen! I'm definitely enjoying the discourse as we find the right place to fit network tokens into UCP 😄

raginpirate · 2026-04-22T02:49:43Z

+### Pre-Provisioned Network Tokens
+
+Not all credential flows require a tokenize/detokenize round-trip. When a
+platform already holds a **card network token** (provisioned via Visa VTS,


nit: I would drop any concern about who provisioned it here to stay bias-free in the protocol documentation 😄

raginpirate · 2026-04-22T02:57:35Z

+the tokenization handler lifecycle entirely — the credential is ready for
+checkout as-is.


Hmm thats interesting: to make this work mechanically, we would require a base dev.ucp.network_token payment handler to allow proper negotiation of direct network token support at checkout + advertising constraints.

Until we decide to deliver something like that (and have a volunteer business & platform adopters), this statement is not necessarily true.

You're right — I've updated the language to cover a payment handler requirement for capability negotiation. The specific handler definition (while perhaps the spirit of what I was after with #296 - but didn't quite nail) is something we tackle in the future. Hopefully you'll find the docs here framing that up correctly now though.

raginpirate · 2026-04-22T03:13:34Z

+Mastercard MDES, or similar), it can present the token directly as a
+`card_credential` with `card_number_type: "network_token"`. This bypasses


Hmmmm... From a business perspective nothing happened involving them, but from a platform perspective they still need to generate a cryptogram, which to me is a form of tokenization process that a handler can/should describe in the ecosystem 😄

Yeah, I'm with you on the need for a handler through which the platform and business can "agree" on use of a network token.

raginpirate · 2026-04-22T03:19:43Z

+
+```json
+{
+  "type": "card",


Aligned and truthfully I think thats what would fit the current state of UCP!

raginpirate · 2026-04-22T03:24:37Z

 Tokenization handlers accept source credentials (e.g., card with FPAN) and
 produce checkout credentials (e.g., tokens).

+### Pre-Provisioned Network Tokens


Just a note that this document, although it uses card as an example, does not actually get into the specifics of how one should handle card tokenization. This context is a bit jarring living here, it might be worth pivoting this to describe secure tokens and using network tokens as an example of reducing compliance risk with a secure tokenization protocol.

Alright - I've tried to reframe the section as "Pre-Provisioned Credentials," with a general pattern of credentials acquired in advance that don't require a per-transaction tokenize/detokenize round-trip. Network tokens are a concrete example of this pattern (though details of provisioning / submitting for payment are outside the scope of this doc) rather than the sole focus. WDYT?

Reframe pre-provisioned network tokens as a general credential pattern: - Rename section to "Pre-Provisioned Credentials" - Drop DPAN qualifier and VTS/MDES API references - Clarify payment handler is required for capability negotiation - Use network tokens as concrete example, not sole focus

jamesandersen

Thanks @kmcduffie and @raginpirate for sticking with this PR - good feedback throughout and hopefully we're getting close with this latest round of updates ;-)

jamesandersen · 2026-04-24T06:13:24Z

 - Using PSP tokenization payment handlers where raw credentials never pass
    through the platform
+- Presenting pre-provisioned card network tokens
+    (`card_number_type: "network_token"`) — DPANs with cryptograms may


Good call — updated the language to say "network tokens with cryptograms" rather than "DPANs with cryptograms," so it covers both DPANs and CPANs without assuming device-binding.

jamesandersen · 2026-04-24T06:15:31Z

+### Pre-Provisioned Network Tokens
+
+Not all credential flows require a tokenize/detokenize round-trip. When a
+platform already holds a **card network token** (provisioned via Visa VTS,


Agreed — dropped the VTS/MDES references.

jamesandersen · 2026-04-24T06:18:50Z

 Tokenization handlers accept source credentials (e.g., card with FPAN) and
 produce checkout credentials (e.g., tokens).

+### Pre-Provisioned Network Tokens


Alright - I've tried to reframe the section as "Pre-Provisioned Credentials," with a general pattern of credentials acquired in advance that don't require a per-transaction tokenize/detokenize round-trip. Network tokens are a concrete example of this pattern (though details of provisioning / submitting for payment are outside the scope of this doc) rather than the sole focus. WDYT?

jamesandersen · 2026-04-24T06:32:58Z

+Mastercard MDES, or similar), it can present the token directly as a
+`card_credential` with `card_number_type: "network_token"`. This bypasses


Yeah, I'm with you on the need for a handler through which the platform and business can "agree" on use of a network token.

jamesandersen · 2026-04-24T06:36:57Z

+the tokenization handler lifecycle entirely — the credential is ready for
+checkout as-is.


You're right — I've updated the language to cover a payment handler requirement for capability negotiation. The specific handler definition (while perhaps the spirit of what I was after with #296 - but didn't quite nail) is something we tackle in the future. Hopefully you'll find the docs here framing that up correctly now though.

jamesandersen · 2026-04-24T06:45:17Z

+
+```json
+{
+  "type": "card",


Yep - language is updated to note a payment handler is needed for negotiation. This should leave the door open for handlers that also that wrap credentials for intermediary opacity.

I'm interested to discuss/learn more about pros/cons of wrapping vs. directly passing network tokens (which the schema seems to allow on a complete checkout call) BUT also interested in getting this PR over the finish line before diving into that further ;-)

jamesandersen requested review from a team as code owners April 17, 2026 07:05

jamesandersen requested review from archrao, kmcduffie, nicholasjameshall and wry-ry April 17, 2026 07:05

ptiper added the payments label Apr 17, 2026

kmcduffie self-assigned this Apr 20, 2026

jamesandersen mentioned this pull request Apr 21, 2026

feat: add card network token credential and instrument types #296

Closed

6 tasks

kmcduffie reviewed Apr 21, 2026

View reviewed changes

raginpirate reviewed Apr 22, 2026

View reviewed changes

jamesandersen force-pushed the docs/network-token-usage branch from 4da321b to ab9db85 Compare April 24, 2026 06:31

jamesandersen commented Apr 24, 2026

View reviewed changes

		the tokenization handler lifecycle entirely — the credential is ready for
		checkout as-is.

		Mastercard MDES, or similar), it can present the token directly as a
		`card_credential` with `card_number_type: "network_token"`. This bypasses

Conversation

jamesandersen commented Apr 17, 2026

Summary

Type of change

Checklist

Uh oh!

kmcduffie commented Apr 20, 2026

Uh oh!

jamesandersen commented Apr 21, 2026

Uh oh!

kmcduffie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raginpirate left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raginpirate Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamesandersen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

raginpirate Apr 22, 2026 •

edited

Loading