The Tokenized Card Payment specification describes the data formats used by the PaymentRequest API [[!PAYMENTREQUESTAPI]] to support payment by tokenized payment cards.


This specification is a Payment Transaction Message Specification used by the PaymentRequest API [[!PAYMENTREQUESTAPI]] to support payment by tokenized payment cards. Merchants should favor tokenized card payment methods over basic card payments.


This specification relies on several other underlying specifications.

Payment Request Architecture
The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [[!PAYMENTARCH]].
Basic Card Payment
The term BillingAddress is defined by the Basic Card Payment specification [[!BASICCARD]].
Payment Request API
The term PaymentRequest constructor is defined by the PaymentRequest API specification [[!PAYMENTREQUESTAPI]].
Payment Method Identifiers
The term Payment Method Identifier is defined by the Payment Method Identifiers specification [[!METHODIDENTIFIERS]].
The IDL in this specification is defined by Web IDL [[!WEBIDL]].

Payment Method Identifier

The following payment method identifier strings are supported by the Tokenized Card Payment data formats.

Identifier StringDescription
urn:payment-method:tokenized-card-payment:networkNetwork Tokenized Cards
urn:payment-method:tokenized-card-payment:issuerIssuer Tokenized Cards

The payment method can be further specified by using the optional supportedTokenTypes data attribute. Payment Mediators will take the supported token types into consideration when presenting Payment Apps to the user.

Payment Method Specific Data for the PaymentRequest constructor

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

        dictionary TokenizedCardSpecificData  {
          required sequence<DOMString> supportedTokenTypes;
          DOMString? merchantID;

The TokenizedCardSpecificData dictionary contains the following fields:

The supportedTokenTypes specifies which network or issuer token providers you support.
Apps that provide tokenization will likely prefer to encrypt the response data with the merchant's public key. How/should that be specified in the input data?
The exact list of supported token types and how this list is updated needs thought.

As an example, you might construct a Payment Request with supported payment methods as follows:

        var supportedMethods = [{
          supportedMethods: ['urn:payment-method:tokenized-card-payment:issuer'],
          data: {
            supportedTokenTypes: ['roypay'],

Payment Method Response

The TokenizedCardResponse dictionary contains the response from the PaymentRequest API when a user accepts payment with a Tokenized Payment Card payment method.

        dictionary TokenizedCardResponse {
            DOMString          cardholderName;
            required DOMString          cardLast4;
            DOMString          cardType;
            DOMString          tokenType;
            required DOMString          tokenNumber;
            required DOMString          expiryMonth;
            required DOMString          expiryYear;
            DOMString        tokenCryptogram;
            DOMString        tokenRequesterId;
            BillingAddress?  billingAddress;
The response should be broken into two different response types, one network tokens and one issuer tokens respectively.

The TokenizedCardResponse dictionary contains the following fields:

The cardholderName field contains the cardholder's name as it appears on the card.
The cardLast4 field contains the last 4 digits of the original (non-token) primary account number (PAN) for the payment card.
The cardType field contains the type (Visa, Mastercard, etc.) of the original (non-token) payment card.
The tokenType field contains the type (Network, Issuer) of token.
The tokenNumber field contains the token number for the payment card.
The expiryMonth field contains a two-digit string for the expiry month of the token in the range 01 to 12.
The expiryYear field contains a two-digit string for the expiry year of the token in the range 00 to 99.
The tokenCryptogram field contains the cryptogram for the token. The cryptogram+token combination establishes a one time use credential. For issuer tokenization, this field should be a CVV.
The tokenRequesterId field contains ID of the requester of the token (likely the creator of the payment app). This field is only applicable to network tokenization.