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.
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.
Your payment services provider can configure the Tokenization service associated with your merchant profile for the following parameters:
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. |
| None | No verification is performed. |
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. |
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:
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:
|
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.
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.
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 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).
The following example request shows how to provide both card details and token sources in the Tokenize request:
| HTTP Method | PUT |
| URL | https://na.gateway.mastercard.com/api/rest/version/72/merchant/<merchant>/token/9999999999999999 |
| JSON |
{
"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.
Performs an Authorize for the specified amount using the payment details identified by the supplied token.
Performs a Pay for the specified amount using the payment details identified by the supplied token.
Allows you to retrieve the payment details saved against the specified token. The account identifier and other sensitive data are returned masked.
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.
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.
Use the Token Maintenance Service, if you do all of the following:
To use the Token Maintenance Service, you must:
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:
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.
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:
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_UPDATERtransaction.currencyNote 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.
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.
This table describes few scenarios where a replacement token is generated.
| Case 1 |
|
| Case 2 |
|
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.
| URL | https://na.gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/token/<token_ID> |
| HTTP Method | PUT |
{
"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"
}
}
}
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