This specification defines a Payment Method used by the PaymentRequest API [[!payment-request]] to support tokenized card payments.

The working group maintains a list of all bug reports that the group has not yet addressed. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

Introduction

A network token replaces the number embossed on a credit or debit card —the primary account number or PAN— with surrogate data. This substitution offers several security benefits:

Network tokens offer additional benefits as well:

Payment networks (e.g., American Express, China Union Pay, Discover, JCB, Mastercard, and Visa) and issuing banks offer services that provide the tokens described by this specification. Data requirements are drawn from the EMVCo specifications [[!EMVCO-TOKENIZATION]] and [[!EMVCO-3DS]].

This document describes how to connect these service providers to the Payment Request [[payment-request]] ecosystem so that merchants can request network and issuer tokens, and users can use payment handlers that request these tokens from service providers.

Examples

Request Example

const methodData = [{
  supportedMethods: ['tokenized-card'],
  data: {
    supportedNetworks: ['mastercard','visa', 'amex', 'discover', 'jcb','unionpay'],
    supportedTypes: ['credit','debit'],
    usageType: 'one-time',
    payeeID: '234987',
    keyProviderURL: 'https://pspKeyProvider.example/tokenizedCardPublicKey',
  }
}];

const details = {
  displayItems: [
    {
      label: "Sub-total",
      amount: { currency: "USD", value: "55.00" },
    },
    {
      label: "Sales Tax",
      amount: { currency: "USD", value: "5.00" },
    },
  ],
  total: {
    label: "Total due",
    // The total is USD$65.00 here because we need to
    // add shipping (below). The selected shipping
    // costs USD$5.00.  
    amount: { currency: "USD", value: "65.00" },
  },
};

new PaymentRequest(methodData, details);
        

Response Example

This example shows some fictitious Mastercard-specific response data.

          {
          displayLast4: "***6789",
          displayExpiryMonth: "02",
          displayExpiryYear: "22",
          displayNetwork: "mastercard",
          encryptedDetails: "QWxobHZ4bU4yWkt1QUFFU05GWjRHb0FCRkE9PQ==", 
          }
        

When decrypted, the encryptedDetails data would be:

          {
          cardNumber: "5413339000001513",
          expiryMonth: "12",
          expiryYear: "20",
          cryptogram: "AlhlvxmN2ZKuAAESNFZ4GoABFA==",
          typeOfCryptogram: "UCAF", // "Universal Card Authentication Field"
          trid: "59812345678",
          eci: "242", // Authorization and final transaction request with UCAF data
          }
        

Assumptions

Payment Method Identifier

The payment method identifier string for the Tokenized Card Payment method is tokenized-card.

TokenizedCardRequest dictionary

This section describes payment method specific data that is supplied as part of the data argument to the PaymentRequest constructor.

        dictionary TokenizedCardRequest{
          sequence<DOMString>       supportedNetworks;
          sequence<BasicCardType>   supportedTypes;
          sequence<DOMString> supportedCryptogramTypes;
          required DOMString              keyProviderURL;
                   TokenUsageType         usageType;
                   DOMString              payeeID;
        };
      

The TokenizedCardRequest dictionary contains the following members:

supportedNetworks member
A sequence of identifiers for card networks that the payee accepts. W3C maintains a list of approved card network identifiers.
supportedTypes member
A card can be of type "credit", "debit", or "prepaid", as derived from the issuer identification number (the first eight digits of the primary account number (PAN). The different types are represented as the BasicCardType enum.
supportedCryptogramTypes member
This member is an optional list of Payment Network-specific strings, each one a cryptogramType. This list describes the types of Token Cryptogram accepted by the payee.
usageType member
A payee may request a TokenUsageType. If not present, the value of this member defaults to "one-time".
payeeID member
This Member is an optional Payment Network-specific string that the Token Service Provider may use to constrain the token for us by a single party. This is called a "merchant identifier" in the EMVCO Tokenization Specification.
keyProviderURL member
This member designates, via a URL, a public key trusted by the Token Service Provider. The source of the key, therefore, becomes the effective requestor of the tokenized-card from a Token Service Provider's perspective.

See What public key formats are acceptable, and any constraints? #1 .

TokenUsageType enum

          enum TokenUsageType { "one-time", "card-on-file", "recurring" };
        
"one-time"
The payee expects to use the token for a single authorization. How exactly the payee can use the token (e.g., for a charge, an update to the authorization, a partial refund, a second partial shipment, or incremental charges) is outside the scope of this specification.
"card-on-file"
The payee expects to re-use the token for as yet uknown future transactions, including payer-initiated transactions and payee-initiated transactions (e.g., for partial shipment, incremental charges, and resubmission use cases). Whether and how the payee requests a new Token Cryptogram for future transactions is outside the scope of this specification. However, the authors of this specification assume that the necessary relationships among relevant parties exist to enable interactions with and between the Token Requestor and Token Service Provider.

"recurring"
The payee expects to re-use the token exclusively for a recurring payment according to an agreement with the payer.

TokenizedCardResponse dictionary

        dictionary TokenizedCardResponse {
                       DOMString       cardholderName;
                       DOMString       displayMaskedCard;
                       DOMString       displayLast4;
           required    DOMString       displayExpiryMonth;
           required    DOMString       displayExpiryYear; 
           required    DOMString       displayNetwork;
                       DOMString       par;
                       DOMString       tokenreferenceid;
                       PaymentAddress? billingAddress;
           required    DOMString       encryptedDetails;
         };
      
cardholderName member
The card holder's name as it appears on the card.
displayLast4 member
It is common for applications to want to display recognizable information about the user's card, without revealing sensitive credentials. This value may be used as a hint, for the common case of displaying the last four digits of the original PAN.
displayMaskedCard member
In some cases, the card issuer may provide an alternative hint to displayLast4. Applications MAY use either displayLast4 or displayMaskedCard as a hint, and SHOULD use only one of them to avoid confusion or leaking information.
displayExpiryMonth member
A two-digit string for the actual expiry month of the card in the range "01" to "12".
displayExpiryYear member
A four-digit string for the expiry year of the actual card in the range "0000" to "9999".
displayNetwork member
The name of the actual Payment Network of the card.
billingAddress member
A PaymentAddress that represents the billing address associated with the card, or null.
par member
This optional member is a Payment Account Reference (or PAR), which enables merchants, acquirers and payment processors to link transactions initiated with affiliated Payment Tokens to transactions based on the underlying primary account number. The value is a composite field consisting of 29 uppercase alphanumeric roman characters. See [[EMVCO-TOKENIZATION]] for more details.
tokenreferenceid member
This optional member is a Token Reference ID, a substitute for the cardNumber that does not expose information about the cardNumber or the underlying primary account number. It is a Payment Network-specific string.
encryptedDetails member
This member is a string that represents EncryptedTokenizedCard information, encrypted with the keyProviderURL according to [[webpayments-crypto]].

EncryptedTokenizedCard dictionary

This dictionary defines the sensitive data that is to be encrypted. Note that the fields of this dictionary do not themselves influence the encryption.

          dictionary EncryptedTokenizedCard {
           required DOMString       cardNumber;
           required DOMString       expiryMonth;
           required DOMString       expiryYear;
           required DOMString       cryptogram;
                    DOMString       typeOfCryptogram;
                    DOMString       trid;
                    DOMString       eci;
          };
        
cardNumber member
This member is a Payment Token.
expiryMonth member
A two-digit string of dynamic data in the range "01" to "12"; this does not represent the actual expiry month of the card.
expiryYear member
A four-digit string of dynamic data in the range "0000" to "9999"; this does not represent the actual expiry year of the card.
cryptogram member
This member is a Token Cryptogram. It is Payment Network-specific and used to ensure the authenticity of the transaction.
typeOfCryptogram member
This member is a Payment Network-specific string that describes the Token Cryptogram type.
trid member
This member is a Token Requestor ID, an 11-digit numeric value that identifies the token requestor (e.g., the payment handler) and is used as part of authorization flows.
eci member
This member is an Electronic Commerce Indicator, a Payment Network-specific string to indicate the results of user authentication.

Interfacing with a payment request

Steps to check if a payment can be made

The steps to check if a payment can be made by a Payment Handler that handles "tokenized-card" takes TokenizedCardRequest request as input. It returns either true or false:

  1. Let cards be a list of cards associated with this payment handler.
  2. If cards is empty, return false.
  3. Let networks be an empty DOMString sequence.
  4. Let types be an empty BasicCardType sequence.
  5. Let cryptograms be an empty DOMString sequence.
  6. Let usage be the value of request["usageType"] if present, otherwise set it to "one-time". If the value of usage is not a legal value of TokenUsageType, set usage to "one-time".
  7. If request["supportedTypes"] is present, append each item in request["supportedTypes"] to types.
  8. If request["supportedNetworks"] is present, append each item in request["supportedNetworks"] to networks.
  9. If request["supportedCryptogramTypes"] is present, append each item in request["supportedCryptogramTypes"] to cryptograms.
  10. For each card in cards:
    1. Let isSupported be the result of running the steps to check if an instrument is supported, passing in card, networks, types, cryptograms, usage
    2. If isSupported is true, then return true.
  11. Return false.

Steps to check if an instrument is supported

The steps to check if an instrument is supported takes as input a card card, a list of type types, a list of network networks, a list of cryptogramType cryptograms and a usageType usage. It returns true if the card is supported, false otherwise.

  1. If types is empty and networks is empty, return true.
  2. If networks is not empty:
    1. If networks does not include the card's network, return false.
  3. If types is not empty:
    1. If types does not include the card's type, return false.
  4. If cryptograms is not empty:
    1. If cryptograms does not include a cryptogramType supported by the payment handler, return false.
  5. If usage is not supported by the payment handler, return false.
  6. Return true.

Steps to respond to a payment request

The steps to respond to a payment request are given by the following algorithm. If the end user inputs or selects a card that meets the constraints of TokenizedCardRequest data, the algorithm returns a card as a TokenizedCardResponse.

  1. Let networks be data["supportedNetworks"], or an empty list if data["supportedNetworks"] is missing.
  2. Let types be data["supportedTypes"], or an empty list if data["supportedTypes"] is missing.
  3. Let key be the result of fetching data["keyProviderURL"]. In case of an error, throw throw an error abort these steps.
  4. Let card be a TokenizedCardResponse.
  5. Set card["cardholderName"] to the card holder's name, or the empty string if the user chooses not to provide it.
  6. To provide a hint to help the user select this card, either set card["displayLast4"] to a string that includes the last four digits of the primary account number (e.g., "*** 5050") or set card["displayMaskedCard"] to a string that represents different non-sensitive information about the card (e.g., "Francine Business").
  7. Set card["displayExpiryMonth"] to two-digit string ranging from "01" to "12", or the empty string if the user chooses not to provide it or the type doesn't require an expiry month.
  8. Set card["displayExpiryYear"] to a four-digit string in the range "0000" to "9999", or the empty string if the user chooses not to provide it or the type doesn't require an expiry year.
  9. Set card["displayNetwork"] to a string that identifies the card network.
  10. Set card["par"] to a 29-character string, or the empty string if not available.
  11. Set card["tokenreferenceid"] to a Token Reference ID string, or the empty string if not available.
  12. If a billing address is not required for this card type, then set card["billingAddress"] to null. Otherwise:
    1. Let redactList be « "phone" ».
    2. Let billingAddress be the result running the steps to create a PaymentAddress from user-provided input with redactList.
    3. Set card["billingAddress"] to billingAddress.
  13. Set cardNumber to a tokenized representation of primary account number, a string of digits that ranges from 10 to 19 digits.
  14. Set expiryYear to two-digit string ranging from "01" to "12", or the empty string if the user chooses not to provide it or the type doesn't require an expiry month.
  15. Set expiryMonth to a four-digit string in the range "0000" to "9999", or the empty string if the user chooses not to provide it or the type doesn't require an expiry year.
  16. Set cryptogram to a Token Cryptogram, a Payment Network-specific string.
  17. Set typeOfcryptogram to a Payment Network-specific string that represents the type of the cryptogram.
  18. Set trid to a Token Requestor ID, an 11-digit numeric value.
  19. Set eci to Electronic Commerce Indicator, a Payment Network-specific string.
  20. Set card["encryptedDetails"] to a string following the steps for response data encryption, where the content encryption key is set to key and the plaintext encryption algorithm takes as input cardNumber, expiryMonth, expiryYear, cryptogram, typeOfcryptogram, trid, and eci.
  21. Return card.

Until such time as we learn of intention by browsers/mediators to implement this specification, we have eliminated discussion of validation in this algorithm.

There is only one class of product that can claim conformance to this specification: a payment handler.

A conforming payment handler MUST:

Security and Privacy Considerations

Dependencies

This specification relies on several other underlying specifications.

Payment Request API
The terms PaymentAddress and PaymentRequest constructor are defined in Payment Request API [[payment-request]].
Payment Method Identifiers
The term payment method identifier and standardized payment method identifier are defined by the Payment Method Identifier specification [[!payment-method-id]].
Basic Card Payment
The terms basic-card, BasicCardType, cards, type, networks, primary-account-number, billing address, and card holder's name are defined in [[!payment-method-basic-card]].
EMVCo Tokenisation
The terms Payment Token, Token Cryptogram, Payment Networks, Token Service Providers, Token Requestor ID, Token Requestor, Merchant Identifier and Tokenized Payment Method Credentials, Token Reference ID, and Payment Account Reference are defined in [[EMVCO-TOKENIZATION]].
EMVCo 3-D Secure
The terms Electronic Commerce Indicator is defined in [[EMVCO-3DS]].
Payment Method Encryption
The steps for response data encryption are described in [[!webpayments-crypto]]. That specification defines the terms content encryption key, message structure, and plaintext encryption.
ISO7812-1
ISO 7812-1 specifies a numbering system for the identification of the card issuers, the format of the issuer identification number (IIN) and the primary account number (PAN).

Appendix: Token Service Provider Considerations

The following Token Service Provider considerations are explicitly out of scope for this specification.

Appendix: Flow Diagrams

Tokenized card payment flow

Acknowledgments

Thanks to Manash Bhattacharjee for his work on this specification.