gateway_params

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 Declaration

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
• tokenProviderURL, required. API endpoint which will be invoked in order to obtain data to be returned to the merchant
• publicKey, required. A public key that will be used to encrypt card data sent to the token provider
• environment, optional. An optional parameter sent to the token provider used to denote a sandbox or live environment

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

enum CardType {
    "credit",
    "debit",
    "prepaid"
};

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

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

dictionary ProviderTokenizedCardRequest {
             sequence<DOMString>       supportedNetworks;
             sequence<CardType>        supportedTypes;
    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',
        environment: 'test',
        oneTimeUse: false
      }
    }
  },
  ...,
];
var payment = new PaymentRequest(
  supportedInstruments,
  details,
  options
);

Tokenization

Request

Following steps 3, 4 and 5, assuming the user chooses a provider tokenized payment method, the Payment Handler will contact the token provider with the parameters provided in the payment method declaration configuring the token provider.

The Payment Handler will send a request to tokenProviderURL, passing the parameters merchantId and environment, but will also send a Base64-encoded encrypted hash, using the publicKey provided, of the basic-card information that would have been sent to the merchant as per the BasicCardResponse specification.

Optionally, the merchant could provide a oneTimeUse parameter, which signals to the payment app that this payment method is not to be saved for subsequent use.

It would look something like:

dictionary TokenizationRequest {
    required DOMString                      merchantId;
    optional TokenProviderEnvironment       environment;
    required DOMString                      cardData;
    optional Boolean                        oneTimeUse;
};

Where cardData is a base-64 encoded string of encrypted data of the following data structure:

dictionary TokenizedCard {
             DOMString       cardholderName;
    required DOMString       cardNumber;
             DOMString       expiryMonth;
             DOMString       expiryYear;
             DOMString       cardSecurityCode;

             PaymentAddress? billingAddress;
};

Response

This section describes steps 7, and 8.

The token provider responds with two parameters:

1. instrumentToken: The implementation of the generation of this instrumentToken is left to the token providers
2. oneTimeUse: this gives the opportunity for the tokenization provider to possibly override the preference submitted in the request and describes to the Payment Handler how to handle the token

dictionary TokenProviderResponse {
             DOMString       instrumentToken;
             Boolean         oneTimeUse;
};

Upon receiving this instrumentToken, the Payment Handler should generate and store a token-provider-merchant-identifier for the combination of the:

• card
• token provider
• merchant checkout page origin

This token-provider-merchant-identifier will be persisted for subsequent 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.

After the instrumentToken is obtained, if oneTimeUse is false, the token-provider-merchant-identifier is generated and stored.

If oneTimeUse is true, the Payment Handler will not store this id.

Afterwards, the payment request API returns data similar to what would be returned by basic-card.

dictionary ProviderTokenizedCardResponse {
             DOMString       cardholderName;
             DOMString       tokenizedCardId;
    optional DOMString       issuerIdentificationNumber;
    optional DOMString       instrumentToken;
    required DOMString       tokenProviderURL;

             PaymentAddress? billingAddress;
};

In the diagram above, the merchant will then use the instrumentToken to obtain the token generated by the token provider via server to server interaction.

The implementation of this interaction will be up to the merchant and the token provider. The token provider could also send the actual token to the client if desired, although it would entail trusting the client's computer not to be compromised in the case of long lived tokens.

A response code will be sent to the merchant checkout page indicating success or failure, as per the Payment Request API.

Subsequent card usage

When the Payment Handler finds the same card, token provider and merchant origin combination, it no longer needs to obtain an instrumentToken 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: