diff --git a/proposals/tokenized_cards.html b/proposals/tokenized_cards.html new file mode 100644 index 0000000..678922b --- /dev/null +++ b/proposals/tokenized_cards.html @@ -0,0 +1,237 @@ + + + + + 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. +

+
+
+

Introduction

+

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

+
+ +
+

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 StringDescription
urn:payment-method:tokenized-card-payment:networkNetwork Tokenized Cards
urn:payment-method:tokenized-card-payment:gatewayGateway 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: +

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