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

This specification is a Payment Method Specification used by the PaymentRequest API [[!payment-request]] to support tokenized card payments. The tokens anticipated by this specification are "network" or "issuer" tokens.

Payment networks such as Mastercard, Visa, and American Express provide tokenization services for credit cards and debit cards. The intention of tokenization is to ensure that a consumer's primary account number (PAN) is not exposed to potentially insecure merchant environments. To increase the security of payment processing, merchants —or their Payment Service Providers (PSPs)— may use tokens along with cryptographically generated dynamic data.

This document describes a payment method that achieves the security goals of EMVCo tokenization specifications, within the usual Payment Request API flow. The payment handler achieves this by leveraging elements of [[EMVCO-TOKENIZATION]] and [[EMVCO-3DS]].

Examples

Request Example

const methodData = [{
  supportedMethods: ["tokenized-card"],
  data: {
    supportedNetworks: ['mastercard','visa', 'amex', 'discover', 'jcb','unionpay'],
    supportedTypes: ['credit','debit'],
    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.

The task force is still discussing whether this specification should include terms common to Basic Card by reference or redefine them in line.

        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
A sequence of identifiers for card networks that the payee accepts. W3C maintains a list of approved card network identifiers.
supportedTypes
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
This member is an optional list of Payment Network-specific strings that describe the types of Token Cryptogram accepted by the payee.
usageType
A payee may request a TokenUsageType. If not present, the value of this member defaults to "one-time".
payeeID
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
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.
"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       displayMaskedCard;
                       DOMString       displayLast4;
           required    DOMString       displayExpiryMonth;
           required    DOMString       displayExpiryYear; 
           required    DOMString       displayNetwork;
           required    EncryptedTokenizedCard encryptedDetails;
         };
      
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.
encryptedDetails member
This member includes EncryptedTokenizedCard information.

EncryptedTokenizedCard dictionary

This dictionary represents data encrypted with the key identified by the keyProviderURL according to [[RESPONSE-DATA-ENCRYPTION]]. 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 set by the Token Service Provider.
eci member
This member is an Electronic Commerce Indicator, a Payment Network-specific string to indicate the results of user authentication.

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 is defined by the Payment Method Identifier specification [[!payment-method-id]].
Basic Card Payment
The terms basic-card and BasicCardType are defined in [[!payment-method-basic-card]].
EMVCo Tokenisation
The terms Payment Token, Token Cryptogram, Payment Networks, Token Service Providers, Token Requestor ID, Merchant Identifier and Tokenized Payment Method Credentials are defined in [[EMVCO-TOKENIZATION]].
EMVCo 3-D Secure
The terms Electronic Commerce Indicator is defined in [[EMVCO-3DS]].
Response Data Encryption
[[!RESPONSE-DATA-ENCRYPTION]] is a work in progress of the Web Payments Working Group.
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.