gateway_params

Status: This is a draft document that does not yet represent the consensus of any group. At this time, the Tokenization Task Force does not anticipate creating a gateway tokenization specification, but discussions reflected in this document are expected to inform discussion about network tokens.

Tokenization using Token Providers

Merchants often choose to use token providers such as gateways to handle credit card payments. This increases security for end users, merchants and allows for multiple payment models for when the card is not present, as token providers often allow re-use of those cards.

The following diagram demonstrates a sequence of client and server-side interactions leading to the generation and storage of tokens on first time use.

Payment Method Specific Data for the PaymentRequest constructor

In step 2 of the diagram, the merchant's backend responds to a user request with a checkout page containing token provider parameters.

These parameters contain information in addition to what's specified in basic-card:

• merchantId, required. Serves to identify the merchant at the token provider. By design, this string is opaque to parties other than the token provider.
• publicKey, optional. A public key that, when present, is used to Base64-encode the CardData sent to the token provider.
• tokenProviderURL, required. This the identifier of the token provider the merchant has a relationship with. This identifier is used to help establish matching payment apps (that interact with that token provider).
• environment, required. This flag enables the merchant to signal to the payment app (and tokenization provider) that a transaction is either a production ("real" transaction) or a test. The default value of this parameter is "production".
• oneTimeUse, required. When true, this boolean indicates that the merchant only accepts one time use tokens. When false, the it means that the merchant requests that tokenization provider store the CardData for subsequent transactions. The default value of this parameter is "false".

An example token provider tokenized payment method specification which would be given to the payment request API:

enum TokenProviderEnvironment {
    "test",
    "production"
};

dictionary TokenProviderParameters {
    required DOMString                    merchantId;
    optional DOMString                    publicKey;
    required DOMString                    tokenProviderURL;
    required Boolean                      oneTimeUse;
    required TokenProviderEnvironment     environment;
};

dictionary ProviderTokenizedCardRequest {
             sequence<DOMString>       supportedNetworks; // Defined in Basic Card
             sequence<CardType>        supportedTypes; // Defined in Basic Card
    required TokenProviderParameters   tokenProviderParameters;
};

This will materialize in Javascript as follows:

var supportedInstruments = [
  {
    supportedMethods: ['provider-tokenized-card']
    data: {
      supportedNetworks: ['amex', 'discover', 'mastercard', 'visa'],
      supportedTypes: ['credit', 'debit'],
      tokenProviderParameters: {
        merchantId: 'ZWMQtaTEyVDb8]FKdNaVmVj2yy;rNG',
        publicKey: 'live_DmF7xVDZKAUpkY]sxjidtRg@6dVPLt',
        tokenProviderURL: 'https://my.payment-gateway.com/webpayment/tokenize',
        oneTimeUse: false,
        environment: 'test'
      }
    }
  },
  ...,
];
var payment = new PaymentRequest(
  supportedInstruments,
  details,
  options
);

Data Exchanged between Payment App and Tokenization Provider

The following subsections describe which data that is present in the payment request is conveyed to the tokenization provider, and the expected result data to the payment app.

Data Sent to Tokenization Provider

Following steps 3, 4 and 5, after selection of a card by the user, the payment handler sends the following information to the token provider:

• CardData (defined in Basic Card)
• merchantId
• oneTimeUse
• environment

The data is structured as follows:

dictionary TokenizationRequest {
    required CardData                       cardData; // May be Base-64 encoded or in the clear
    required DOMString                      merchantId;
    optional TokenProviderEnvironment       environment;
    optional Boolean                        oneTimeUse;
};

dictionary CardData {
             DOMString       cardholderName;
    required DOMString       cardNumber;
             DOMString       expiryMonth;
             DOMString       expiryYear;
             DOMString       cardSecurityCode;
};

Data Received from Tokenization Provider

This section describes steps 7, and 8.

The token provider responds with two parameters:

• token: This is a representation of the token returned by the token provider. By design, this string is opaque to parties other than the token provider.
• oneTimeUse: This boolean indicates whether the token is for one time use, whatever the preference the merchant expressed in the payment request. A value of 'true' indicates that it is for one time use.

dictionary TokenProviderResponse {
             DOMString       token;
             Boolean         oneTimeUse;
};

Upon receiving this token, the Payment Handler should generate a tokenProviderMerchantIdentifier for the combination of the:

• cardData
• tokenProviderURL
• merchant checkout page origin

If oneTimeUse is false, the payment handler stores the tokenProviderMerchantIdentifier for subsequent transactions. If oneTimeUse is true, the payment handler does not store the tokenProviderMerchantIdentifier.

The tokenProviderMerchantIdentifier is generated by the Payment Handler to minimize the exposure of the token from potential eavesdroppers on the client machine. It will be used for subsequent usages instead of the token, which is never persisted and only sent on the initial use.

Payment Request Response

This section describes steps 9, 10, 11, 12, 13 and 14 in the diagram, where 11-14 are outside of the scope of the specs described.

The response data for the tokenization payment method resembles the response data for basic-card.

dictionary ProviderTokenizedCardResponse {
             DOMString       cardholderName;
             DOMString       tokenProviderMerchantIdentifier;
    optional DOMString       issuerIdentificationNumber; // First six to eight digits of card number
    optional DOMString       token; // In multi-use scenarios, the token is not returned to merchant
                                   //  after the first transaction
    required DOMString       tokenProviderURL; // Identifies selected token provider 
};

Note: Exception handling is addressed in the Payment Request API specification.

Subsequent card usage

When the Payment Handler finds the same card, token provider and merchant origin combination, it no longer needs to obtain an token from the token provider.

In which case, the interactions will manifest as follows:

Exceptions

In case either the token provider or the merchant encounter exceptions, they should be handled as one entity.

i.e. the error handling should be no different than the current implementation in Payment Request when there was only one network entity to be reached.

This will minimize UX issues

Use-cases

Nonce Passing

One of the use-cases of this is with Payment Gateways such as Braintree or Stripe.

Those gateways currently send a nonce as instrument token to the client. The token that will be long-lived is only exchanged server-to-server.

Direct Token Passing

Another possible implementation is exactly the same as the Nonce Passing, except for providing the actual token to the client, which is then passed to the merchant.

This behavior is entirely up to the merchant and the token provider. A token-provider-merchant-identifier is still generated and the token is never stored on disk by the Payment Handler.

This saves one roundtrip by the merchant to the token provider, at the cost of security, but gaining in convenience.

Token Providers and Payment Processors are different parties

There is a use-case where token providers and payment processors will be different entities. Note that the spec is unchanged. It allows for this use-case and the following diagram illustrates how this could be implemented.

Token Providers and IIN routing

The merchant, when communicating with the Token Provider, may have multiple acquirers registered.

The merchant makes a decision on which acquirer to use depending on the issuerIdentificationNumber. This is to increase acceptance rates, to diminish costs or to increase redundancy.

The following diagram illustrates this use-case:

The following depicts an example network topology between a merchant, payment gateways and acquirers:

Subscription service

One of the main use-cases of using tokens from a Tokenization Provider is to be able to charge while the user is not present. A subscription service is an example use-case of this behavior.

After the initial payment, the token is provided to the merchant, which stores this for later use.

Then, every month, the merchant can charge the user while the user is not present.