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.


  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 PAN, 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 a 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.
For device payment transactions using DPAN, if the merchant is configured with the Token Verification Strategy as Acquirer, then the token verification strategy automatically falls back to Basic for processing that specific transaction.
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.
Acquirer Tokenization The token ID is supplied by the acquirer tokenization service. This service only allows for storing the FPAN in a token. The following prerequisites must be met to allow acquirer tokenization:
  • The token verification strategy to verify card details is set to None
  • The token management strategy for the token repository is set to Unique Account Identifier.
  • You are set up with only one acquirer link that has the acquirer tokenization capability.
For more information on acquirer tokenization, please contact your payment service provider.

Token Operations

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


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.

You can also use this operation to create or update a token by providing the reference order ID of a previous successful order, which can be up to 12 months old in the gateway. You are provided with a gateway token against the payment credentials used in the referenced order. The token is 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.

The gateway supports automatic as well as manual account updates for tokens. For more information, see Token Maintenance Service and Manual Account Updates respectively.

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:

  "sourceOfFunds": {
    "provided": {
      "card": {
        "expiry": {
          "month": "01",
          "year": "39"
        "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 gateway tokenization 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).
  • Ask your payment service provider to enable Token Maintenance Service. Note that you can only be enabled for either the Token Maintenance Service or Network Tokenization, but not both. Both features ensure that the payment details stored against the tokens are kept up-to-date.
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

Use the Retrieve Token operation to retrieve payment details for a token that has been updated by Account Updater.

  • 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]

Manual Token Updates

If you are enabled for Account Updater on your merchant acquirer link(s), you can manually request for account update information on card details stored in a token. To do this, provide the following in the Tokenize request:

  • verificationStrategy=ACCOUNT_UPDATER
  • transaction.currency

Note that providing sourceOfFunds parameter group is optional.

The gateway will receive and process the response from the Account Updater Service similar to when the Token Maintenance Service is used. For information on what token updates include, invalid tokens, and retrieving token update information, see the sections under Token Maintenance Service.

Replacement Token

When the gateway receives an Account Updater response from an acquirer, indicating that the card number has changed, the gateway cannot update the card details due to the token generation or maintenance strategy. Instead, the gateway creates a new token with the new Funding Primary Account Number (FPAN) and then links the new token to the old token using the replacementToken field.

This section explains different scenarios when the merchant must use the replacement token and delete the old token.

If a merchant attempts to update a token, the gateway will reject the request because the gateway has already set a replacement token. The merchant should use the replacement token instead of the old token and remove the old token.

This table describes few scenarios where a replacement token is generated.

Case 1
  • The token repository is configured for the token generation strategy, such as 'Preserve 6.4' or 'Acquirer'.
  • The token is flagged for an account update request using the 'Manual Token Updates' or the 'Token Maintenance Service'.
  • The account updater response indicated that the card has been replaced with a card with a new card number.
Case 2
  • The token repository is configured for the token management strategy 'Unique Account Identifier'.
  • The token is flagged for an account update request using the 'Manual Token Updates' or the 'Token Maintenance Service'.
  • The account updater response indicated that the card has been replaced with a card with a new card number.
  • An active token with the same account identifier already exist in the token repository.

Tokenizing PayPal Billing Agreement ID

PayPal allows you to set up a billing agreement for a payer that allows you to subsequently charge the payer without the payer's consent by referencing the billing agreement. The payer only needs to give consent to the billing agreement once, when it's established. A payment may or may not be performed at the time of setting up the billing agreement.

You can tokenize the PayPal Billing Agreement ID using the Tokenize operation. Provide the token ID, either gateway-generated or the one supplied by you, in the Tokenize request URL.

Example Request
          "sourceOfFunds": {
              "provided": {
                  "paypal": {
                      "billingAgreement": {
                          "description": "Test Billing Agreement",
                          "name": "Test Name",
                          "cardinality": "MULTIPLE",
                          "id": "1234"
              "type": "PAYPAL",
                      "token": "9926675679589987"
                    "shipping": {
                     "address": {
                                "city": "city",
                                "country": "country",
                                "postcodeZip": "post_code",
                                "stateProvince": "state",
                                "street": "test street",
                                "street2": "test street2"

Testing your Integration

You can test your integration for gateway tokenization using your test merchant profile (your merchant ID prefixed with TEST) in Production.

The gateway creates two repositories, test and production, when you are enabled and configured for tokenization by your payment service provider. The test repository is your token repository ID prefixed with TEST.

When you submit tokenization requests to the gateway using your test merchant profile, the test token repository is used. To subsequently process a payment with a token, you must tokenize a supported test card number. For test card details, see Test and Go Live.

Copyright © 2023 Mastercard