Tokenized-Card 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);
        

Tokenized-Card Response Example

This example shows some fictitious Mastercard-specific response data.

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

          {
          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
          }
        

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;
          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.

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 .

For more information about handling of supportedNetworks and supportedTypes see the steps to check if an instrument is supported.

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).

"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;
                       DOMString       eci;
                       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.

eci member

This optional member is an Electronic Commerce Indicator, a Payment Network-specific string to indicate the results of user authentication. For related discussion about authentication, see [[3ds]].

encryptedDetails member

This member is a string that represents EncryptedTokenizedCard information, encrypted with the keyProviderURL according to [[webpayments-crypto]].

          dictionary EncryptedTokenizedCard {
           required DOMString       cardNumber;
           required DOMString       expiryMonth;
           required DOMString       expiryYear;
           required DOMString       cryptogram;
           required DOMString       typeOfCryptogram;
           required DOMString       trid;
                    DOMString       tokenRequestorKey;
          };
        

TokenReferenceRequest dictionary

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

        dictionary TokenReferenceRequest{
          sequence<DOMString>       supportedNetworks;
          sequence<BasicCardType>   supportedTypes;
                   TokenUsageType         usageType;
                   DOMString              payeeID;
        };
        

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.

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.

TokenReferenceResponse dictionary

        dictionary TokenReferenceResponse {
                  required DOMString       tokenReferenceID;
                  required DOMString       trid;
                  };
              

tokenReferenceID member

This member is a Payment Network-specific Token Reference ID that the payee uses on the backend to retrieve additional information about the card.

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.

TokenCryptogramRequest dictionary

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

        dictionary TokenCryptogramRequest{
           required DOMString   tokenRequestorID;
                    DOMString   tokenReferenceID;
                    DOMString   encryptedCardNumber;
        };
      

The TokenCryptogramRequest dictionary contains the following members:

tokenReferenceID member

This member is a Payment Network-specific Token Reference ID that represents the stored token for which the payee is requesting a new cryptogram.

encryptedCardNumber member

This optional member is an encrypted Payment Token. Although the tokenReferenceID is preferred it may not always be available, in which case the payee may provide this Payment Token instead, encrypted with the tokenRequestorKey, for example that was returned through the tokenized-card payment response.

Need more details on encryption.

tokenRequestorID member

This member identifies the payment handler used to request the original token. It is an 11-digit numeric value that is a Token Requestor ID. The user agent uses this information to provide a path to the Token Service Provider through the payment handler that requested the original token. It is assumed that the payment handler also has a means to validate that the payee requesting the cryptogram is authorized to do so.

TokenCryptogramResponse dictionary

          dictionary TokenCryptogramResponse{
               required DOMString cryptogram;
               required DOMString typeOfCryptogram;
                        DOMString eci;
          };
      

cryptogram member

This member is a Token Cryptogram.

typeOfCryptogram member

This member is a Payment Network-specific string that describes the Token Cryptogram type.

eci member

This optional member is an Electronic Commerce Indicator, a Payment Network-specific string to indicate the results of user authentication. For related discussion about authentication, see [[3ds]].

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. 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.
10. 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, and a usageType usage. It returns true if the card is supported, false otherwise.

1. If types is empty and networks is empty and cryptograms 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 one of the supportedTypes of 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.

First request for one-time use, recurring, card-on-file token

This diagram illustrates one flow where a payee requests a token (or token reference id) for one-time use, recurring, or card-on-file.

Subsequent cryptogram request for previous card-on-file token

This diagram illustrates a request for a subsequent cryptogram based on a previously stored token.