Card Tokenization

Card Tokenization

The Card Tokenization Service allows merchants to store card data relating to a transaction in the form of a token, without storing the actual card number. This enables further payments to be made by supplying the token in place of the card number. Although storing a Token alleviates some of a merchant’s responsibility with respect to PCI, it does not remove it completely. A merchant who captures card data before passing it to MasterCard Payment Gateway Services is still responsible for ensuring their systems are PCI compliant.

This service can be used in conjunction with any service involving a card number. These include:


  • Bank Card
  • Payments to Card Collection Accounts
  • PPT
  • Fuels
  • MPI Only
  • RBS Gift Card
  • Recurring Transactions
  • Historic Recurring Cards
  • Capture Method Recurring Transactions
  • Pre-Registered Card Service
  • Fully Hosted Payments Pages
  • Hosted Card Capture
  • Batch Input

When using this service, there are two stages. The first tokenizes card details as they are used. The second stage is to use that token for a subsequent transaction.

Tokenize a card number

When using this service, your MasterCard Payment Gateway Services account will be configured with a shared secret key. The shared secret is pre-configured or a specific merchant defined shared secret can be provided to MasterCard Payment Gateway Services. Alternatively the shared secret can be provided with each transaction. Each time a card number is sent to your account, MasterCard Payment Gateway Services will use a Secure Hash Algorithm and shared secret to encrypt the card number and convert this to a unique token . The token will be returned  within the transaction response.

The card payment details can collected from the cardholder via the MasterCard Payment Gateway Services Hosted Payment page or from within your own systems. Tokens will be generated each time a card payment is submitted to your account. Tokens can also be generated without making a payment on the card and may be shared across multiple accounts.

Using Tokens

When you wish to take a payment from a card token, simply send the token in the place of the card number.


Before you can go live with the Card Tokenization Service, you will need the following:

  • A MasterCard Payment Gateway Services account configured with a Card Processing service.
  • The Card Tokenization Service configured on the account.
  • A shared secret key configured on the account. You may provide your own key, or MasterCard Payment Gateway Services will generate a key on your behalf

If you have more than one MasterCard Payment Gateway Services account and wish to use tokens generated on one account on the others, these will be configured as a vTID group with the same secret key.

Transaction Processing Models

Using the Card Tokenization Service, there are three ways in which cards can be allocated tokens. By sending a:

  • normal transaction with a card number.
  • tokenize transaction.
  • query on an existing transaction.

Transaction Type


auth, pre, refund, erp, txn_refund, fuel_validate, fuel_offline_auth_settle, fuel_online_auth, fuel_settle, mpi, top_up, redeem, refund, balance_enquiry, reversal

Processes card transaction as normal. Token is included in response


Returns details of existing transaction, plus token


Turns a card number into a token

Once a card number has been tokenized by any one of these three methods, it may be used in place of the card number for any transaction.

Performing Transactions

Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.

Tokenize a card number

Once the Card Tokenization Service is configured on your account, all attempted authorizations and query transactions will automatically return the token for that card.

If you wish to tokenize a card number without attempting authorization, the following details are required:

  • unique reference number generated by your system - to allow the transactions to be distinguished from each other
  • the transaction type of tokenize
  • the card number

All transactions will automatically use the shared secret key which is configured on your account. If you wish to use a different key, this may be supplied within the transaction.

All tokens have an initial lifespan of four years. Each time the token is subsequently used, it's lifespan will be re-set back to four years.

Using Tokens

In order to use an existing token to take a payment from, simply supply the token instead of the card number. As the token only relates to the card number, any other information specific to the card - such as cv2 and expiry date - must be supplied separately if this is required for the transaction type you are using.

Expire Token or Re-tokenize a card number

Any existing token may be cancelled and replaced by a new one, if required. This is done by sending a tokenize transactions, along with a new shared secret key.

Response Codes

There are a range of response codes that may be generated when using Card Tokenization.

A complete list of Response Codes is available in the Developers Area. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.


The Reporting Details page will display the token for any transaction which has been processed using a token, or for which a token has been generated.

Subscribed merchants will be able to search for transactions using the token.

The Reporting System also enables tokens to be downloaded via configurable CSV.