Gateway Tokenization

Gateway Tokenization allows you to store payment details in exchange for a token. The token replaces the payment details in the transaction request sent to the gateway. This is useful as the gateway handles the payment details collected from the payer thereby reducing your PCI compliance obligations. Further, if the token is stored with the payer data, it may be used when the payer returns to make another purchase.

What Is a Token?

A token is an identifier of stored payment details; returned when you tokenize them. The token may be used for all subsequent payment transactions to refer to the previously saved payment details.

Tokens are in PAN format and will pass simple card validation rules, so that they can be stored in place of credit card numbers. However, their generation is designed to minimize the likelihood that they will be valid card numbers.

Key Benefits

  • Reduces PCI compliance costs as you do not handle or store any payment details.
  • Reduces internal fraud as your staff has limited access to payment details.
  • Allows you to update payment details stored against a token. This is useful when payment details expire/change or the payer wishes to change the payment method.
  • Facilitates ease of integration of tokens into systems that currently expect card numbers. Tokens generated by the system can appear like card numbers and pass basic card validation checks.
  • Allows you to retrieve payment details from a token.
  • Offers different options for verifying payment details.
  • Provides flexible options for token management.
  • Allows you to share tokens with other merchants.

Examples

  1. Recurring Billing (utility bills, gym membership, etc): Collect payment details from the payer and store them in exchange for a token. The token is submitted to the gateway as the payment instrument each time a payment is due. This is useful if you wish to reduce PCI costs.
  2. Online Retailers (online shopping carts, online bill payment, gaming sites): Collect payment details from the payer on a website and store them in exchange for a token. The returned token is stored with the payer data. When a payer returns to the website to make another purchase, you present the masked account identifier (or last four digits of the token, if using the Preserve 6.4. Generation Strategy) and indicate that payment details do not have to be re-entered. This saves payers from having to re-enter some or all of the payment details. It improves convenience and payers' user experience when making purchases through your website.

Configure Gateway Tokenization

Your payment services provider can configure the Tokenization service associated with your merchant profile for the following parameters:

Token Verification Strategy

Defines how the payment details are verified prior to being stored. Values can be:

Basic Validates that the payment details provided conform to the gateway rules for processing a payment with these payment details.
Acquirer Verifies the payment details by performing an API Verify request, to verify the provided payment details with the acquirer.
When you store a token, you must provide a currency. The transaction source will default to the value configured for the merchant-acquirer link. The Enforce CSC setting for this transaction source will be ignored.
None No verification is performed.
Token Management

Defines how tokens within the repository are managed. Values can be:

Unique Token Assigns a unique token every time you save an account identifier. This can be defined as a one-to-many relationship between an account identifier and tokens.
Unique Account Identifier An account identifier can only be stored against a single token. If an attempt is made to store it against another token, it will result in an error. This can be defined as a one-to-one relationship between the account identifier and the token.
Token Generation Strategy

Defines the strategy used to generate a token within this repository. Values can be:

Random with Luhn The generated token id is a random number. It begins with a '9', passes a Luhn (Mod-10) check, and excludes known card numbers.
Preserve 6.4 Attempts to preserve the first 6 and last 4 digits, and is not a valid card number.

Token properties:

Account identifier length Token digits
<=16 16
17 17
18 18
>=19 19

Account identifier length Preserved digits
11 First 5 and last 2
12 First 5 and last 3
13 First 6 and last 3
>13 First 6 and last 4
You cannot update the card number for a preserve 6.4 token; however, you may update the expiry date.
Merchant-Supplied The token is supplied by the merchant. Any merchant-supplied token is validated to not be a valid card number.

Token Operations

You can perform the following operations using the Gateway Tokenization solution:

Tokenize

You can use this operation to create or update a token by storing payment details against the token. The token will be stored in the token repository as configured on your merchant profile.

The payment details will be verified using the verification method provided in the verificationStrategy field. If you do not provide this field, the default strategy configured on your merchant profile will be used. You can set the verificationStrategy to NONE if you want to store tokens without the expiry date. If the verification is successful, the payment details are saved against a token for later reference and used in subsequent payment transactions. You may choose to retry a Tokenize operation if the first attempt does not return a response.

The token is issued based on the token management method configured for the token repository used by your merchant profile.

You can share a token respository with other merchants. Ask your payment service provider for details.

Updating a token without having to recapture all details

You may want to update details (e.g. the expiry date of a card) on a stored token using the Tokenize operation, but leave other details unchanged. The token you supply in the request URL identifies the token you wish to update. Supplying this same token as a source of payment details will cause your previously stored details to be reused. This means you do not need to recapture the payment details. By providing the new expiry date in the Card Details section of the request, the value will override the expiry date already stored in the token (see Precedence Rules).

Updating a token with a different source of funds (e.g. replacing card payment details with Automated Clearing House payment details) will replace all the payment details stored against the token with those from the new source of funds.

The following example request shows how to provide both card details and token sources in the Tokenize request:

HTTP MethodPUT
URLhttps://credimax.gateway.mastercard.com/api/rest/version/56/merchant/<merchant>/token/9999999999999999
JSON
{
	"sourceOfFunds": {
		"provided": {
			"card": {
				"expiry": {
					"month": "05",
					"year": "21"
				},
				"number": "5123456789012346"
			}
		},
		"type": "CARD"
	}
}

The above JSON assumes that a token with id "9999999999999999" was previously stored and contains a card number and expiry date.

The result of this operation will be that token "9999999999999999" now has an expiry date of 05/21, with the card number remaining unchanged.

Tokenization API Reference[REST][NVP]

Authorize with Token

Performs an Authorize for the specified amount using the payment details identified by the supplied token.

Authorize API Reference[REST][NVP]

Pay with Token

Performs a Pay for the specified amount using the payment details identified by the supplied token.

Pay with Token API Reference[REST][NVP]

Retrieve Token

Allows you to retrieve the payment details saved against the specified token. The account identifier and other sensitive data are returned masked.

Retrieve Token API Reference[REST][NVP]

Delete Token

Deletes the specified token from your token repository.

Delete Token API Reference[REST][NVP]

Search Tokens

Finds token records that match a query. The query currently supports searching using a token identifier or an account identifier. Ensure that you encrypt the card number using JWE.js library.

If the query matches a large number of token records, you can limit the search results returned per page and retrieve the next set of results using subsequent requests.

Search Token API Reference[REST][NVP]

Token Maintenance Service

The Token Maintenance Service provided by the gateway ensures that, wherever possible, payment details stored against a token that is used for recurring payments are current and that processing of recurring payment transactions using this token is likely to succeed.

This functionality is currently available only for credit cards.
When to Use the Token Maintenance Service

Use the Token Maintenance Service, if you do all of the following:

  • Process recurring payments via the gateway.
  • Use the Tokenization functionality provided by the gateway to securely store credit payment details used for recurring payments.
  • Use the API and/or Batch to manage your tokens and submit transactions for processing.
The Token Maintenance Service uses the Account Updater functionality provided by card schemes and acquirers. Therefore, only tokens used for transactions processed by Account Updater enabled acquirers can be maintained.
Configure the Token Maintenance Service

To use the Token Maintenance Service, you must:

  • Sign up for Account Updater functionality with your acquirer and the card schemes.
  • Ask your payment service provider to enable Account Updater on your merchant acquirer link(s).
Token Updates

For recurring transactions where a token is provided and the transaction is successfully processed by the gateway via an Account Updater enabled acquirer, the gateway will determine the next date the token will be used for a recurring payment (based on the previous use of the token in recurring payments).

The gateway will submit a request for the payment details stored against the token to the Account Updater service, in time for the gateway to receive and process a response. It will then update the token depending on the response.

Token updates include:

  • Card number and expiry date.
  • Just the card expiry date.
  • Marking a token as invalid.
The Token Maintenance Service respects the token management strategy configured for your token repository. For example, if the token repository is configured with a token generation strategy of Preserve 6.4 and an account update indicates that the expiry date has changed, the token is updated. However, if the card number has changed, the token is marked as invalid.
Invalid Tokens

A token is marked as invalid, if an Account Updater response indicates that the payment details stored against the token are invalid.

Transaction requests using an invalid token are rejected by the gateway.

For an invalid token, the API RETRIEVE_CARD operation response returns status=INVALID.

You can clear an invalid status by updating the payment details stored against the token.

Retrieve Token API Reference[REST][NVP]

Retrieve Token Update Information

When retrieving the payment details for a token that has been updated by Account Updater via the API RETRIEVE_CARD operation:

  • usage.lastUpdated has the date and time the token was updated by Account Updater.
  • usage.lastUpdateBy is empty, indicating that the token was not updated by a merchant but by Account Updater.

Using the API SEARCH_TOKEN operation, you can search for all tokens that have been updated since a specified date and time. The response provides you with all tokens (including payment details stored against the token as well as the usage information for the token) that have a usage.lastUpdated date and time after the date in time provided in the request.

You can now use your existing processes to, for example:

  • Update your system with the new masked card number and/or expiry date returned in the transaction response.
  • Contact customers to obtain new payment details for invalid tokens.
  • Create new tokens if required.

Search Token API Reference[REST][NVP]

Retrieve Token API Reference[REST][NVP]

Copyright © 2020 Mastercard