diff --git a/.cspell/custom-words.txt b/.cspell/custom-words.txt index c46d3595..f5431f69 100644 --- a/.cspell/custom-words.txt +++ b/.cspell/custom-words.txt @@ -26,6 +26,7 @@ Kroger Lowe's Macy's Mastercard +MDES Paymentech Paypal Preorders diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 1265aef6..0c7fd4b8 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1464,6 +1464,12 @@ Most platform implementations can **avoid PCI-DSS scope** by: - Forwarding credentials without the ability to use them directly - Using PSP tokenization payment handlers where raw credentials never pass through the platform +- Presenting pre-provisioned card network tokens + (`card_number_type: "network_token"`) — network tokens with + cryptograms may qualify for reduced PCI scope compared to handling + FPANs directly; consult current + [PCI DSS guidance](https://www.pcisecuritystandards.org/) + for applicable requirements #### Business Scope diff --git a/docs/specification/tokenization-guide.md b/docs/specification/tokenization-guide.md index c574b6fb..eeb15304 100644 --- a/docs/specification/tokenization-guide.md +++ b/docs/specification/tokenization-guide.md @@ -68,6 +68,48 @@ Tokenization handlers transform credentials between source and checkout forms: Tokenization handlers accept source credentials (e.g., card with FPAN) and produce checkout credentials (e.g., tokens). +### Pre-Provisioned Credentials + +Not all credential flows require a tokenize/detokenize round-trip per +transaction. In some cases, a platform may have acquired credentials in +advance — for example, by provisioning a card network token via the +network's token service — and can present them in place of tokenizing an +FPAN at each transaction. Although no credential transformation occurs, +a payment handler is still required for capability negotiation — the +handler advertises support for this credential type so that platforms and +businesses can discover and agree on its use. + +Card network tokens are one such case. When a platform already holds a +network token, it can present the token directly as a `card_credential` +with `card_number_type: "network_token"`: + +```json +{ + "type": "card", + "card_number_type": "network_token", + "number": "4000000000000002", + "expiry_month": 12, + "expiry_year": 2027, + "cryptogram": "gXc5UCLnM6ckD7pjM1TdPA==", + "eci_value": "07" +} +``` + +Key differences from the tokenize/detokenize flow: + +| Aspect | Tokenize/Detokenize | Pre-Provisioned Credential | +| :----- | :------------------ | :------------------------- | +| Source | Platform holds FPAN | Platform holds network token provisioned in advance | +| Flow | Platform → handler `/tokenize` → token per transaction | Platform presents credential directly | +| Cryptogram | Not applicable | Required — generated by the token service | +| PCI scope | Platform may handle raw PANs | May be reduced — consult current [PCI DSS guidance](https://www.pcisecuritystandards.org/) for applicable scope | + +When a handler's `available_instruments` includes +`requires_card_verification: true`, the platform **MUST** provide the +`cryptogram` and `eci_value` fields for network token credentials. See +the [Card Constraints](payment-handler-guide.md#card-constraints) section +in the Payment Handler Guide for details. + ### Token Lifecycle Tokens move through distinct phases. Your handler specification must document diff --git a/source/schemas/shopping/types/card_credential.json b/source/schemas/shopping/types/card_credential.json index 0d08cc79..7db8fece 100644 --- a/source/schemas/shopping/types/card_credential.json +++ b/source/schemas/shopping/types/card_credential.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$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 network token with cryptogram and ECI, which may qualify for reduced PCI scope — consult current PCI DSS guidance for applicable requirements. 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.", "allOf": [ { "$ref": "payment_credential.json"