Tokenized Card Payment

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

Dependencies

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]].
Web IDL: 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 String	Description
urn:payment-method:tokenized-card-payment:network	Network Tokenized Cards
urn:payment-method:tokenized-card-payment:gateway	Gateway Tokenized Cards
urn:payment-method:tokenized-card-payment:issuer	Issuer 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:

supportedTokenTypes: The supportedTokenTypes specifies which network, gateway, or issuer token providers you support.
merchantID: The merchantID is used for gateway tokenization to determine if the merchant has been onboarded to support gateway tokens via this Payment App.

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:gateway'],
          data: {
            supportedTokenTypes: ['roypay'],
            merchantID: '12345abcdef'
          },
        }];

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;
            DOMString        gatewayToken;
            DOMString        gatewayTokenType;
            BillingAddress?  billingAddress;
        };

The response should be broken into three different response types, one network tokens, gateway tokens and issuer tokens respectively.

The TokenizedCardResponse dictionary contains the following fields:

cardholderName: The cardholderName field contains the cardholder's name as it appears on the card.
cardLast4: The cardLast4 field contains the last 4 digits of the original (non-token) primary account number (PAN) for the payment card.
cardType: The cardType field contains the type (Visa, Mastercard, etc.) of the original (non-token) payment card.
tokenType: The tokenType field contains the type (Network, Issuer, Gateway) of token.
tokenNumber: The tokenNumber field contains the token number for the payment card.
expiryMonth: The expiryMonth field contains a two-digit string for the expiry month of the token in the range 01 to 12.
expiryYear: The expiryYear field contains a two-digit string for the expiry year of the token in the range 00 to 99.
tokenCryptogram: The tokenCryptogram field contains the cryptogram for the token. The cryptogram+token combination establishes a one time use credential. This field is only applicable to network tokenization and issuer tokenization. For issuer tokenization, this field should be a CVV.
tokenRequesterId: 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.
gatewayToken: The gatewayToken field contains the gateway token used to process the payment.
gatewayTokenType: The gatewayTokenType field contains the type of gateway tokenization used (i.e. braintree, stripe, etc.)

Introduction

Dependencies

Payment Method Identifier

Payment Method Specific Data for the PaymentRequest constructor

Payment Method Response