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

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.

Sending comments on this document

If you wish to make comments regarding this document, please raise them as GitHub issues. Only send comments by email if you are unable to raise issues on GitHub (see links below). All comments are welcome.


This specification is a Payment Transaction Message Specification used by the PaymentRequest API [[!PAYMENTREQUESTAPI]] to support payment by tokenized payment cards.

Tokenization provides some advantages over traditional card payments - tokenized credentials are often narrowly scoped, for example single-use or merchant/amount/time scoped. Tokenized credentials also help alleviate some concerns about merchant data breaches since the merchant does not have the raw PAN. This provides some additional security for a consumer.


This specification relies on several other underlying specifications.

Basic Card Payment
The term BasicCardResponse 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 payment method identifier string for the Tokenized Card Payment method is card-token.

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.


        enum TokenCardType { "emv", "issuer" };

        dictionary TokenCardRequest {
          sequence<DOMString> supportedNetworks;
          sequence<TokenCardType> supportedTypes;

The TokenCardRequest dictionary contains the following fields:

The supportedNetworks field contains a sequence of identifiers for card networks that the merchant accepts. See Card Network Identifiers Approved for use with Payment Request API for approved values.
The supportedTypes field contains a sequence of token card types that the merchant accepts. The values mean the following:
  • "emv": These are tokens (typically single-use) provided by card networks (cf. supportedNetworks) that represent the underlying PAN.
  • "issuer": With these tokens, a provider serves as a card issuer by generating a new card number. This new card number is backed by the original PAN or by another funding source. During charging of these tokens, the provider translates the generated card number back into the original PAN or original funding source.

The supportedNetworks and supportedTypes fields are both optional. If neither is provided then any card may be returned. If only supportedNetworks is provided then any card type may be returned provided it matches one of the networks. If only supportedTypes is provided then a card may be returned from any network provided it matches one of the types.

Implementations will determine how to match values of supportedTypes.

This specification covers a limited number of supportedTokens. Although there are other types of tokens such as gateway tokens, because they involve substantially different flows of information (e.g., merchant onboarding), this specification does not cover them.

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. The intention is for this to extend from the BasicCardResponse (defined in [[!BASICCARD]]) with some additional fields required for tokenization. It should be noted that the "cardSecurityCode" from the BasicCardResponse will contain a card security code for issuer-based tokens, but will contain the cryptogram for network tokens. The combination of cardNumber (the token number) + cardSecurityCode (either cryptogram or security code) establishes a one-time use credential.

        dictionary TokenizedCardResponse: BasicCardResponse {
            required DOMString          cardLast4;
            DOMString          tokenType;
            DOMString        tokenRequesterId;

The TokenizedCardResponse dictionary contains the following fields:

The cardLast4 field contains the last 4 digits of the original (non-token) primary account number (PAN) for the payment card. This may be used for display purposes during the purchase.
The tokenType field contains the token type selected by the user. This is one of the values of supportedTypes.
The tokenRequesterId field contains ID of the entity that requested the token from the network (likely the creator of the payment app). This field is only applicable when tokenType is "emv".

Appendix: Flow Diagrams

Issuer Token Flow

issuer token flow

Network Token Flow

network token flow