Tokenization means the replacement of a sensitive piece of information (i.e.: credit card number) with a non sensitive one, called Token.
Tokenization and Iframe solutions are available to Enterprise users.
Tokenization is used within Gestpay in order to help merchants to match PCI-DSS requirements, defined by all major credit cards companies in order to protect sensitive data of cardholders.
Merchants, who ask to their customers to register in their online shop, often save the customer’s credit card data in their system.
This behaviour has many advantages, first of which is the fact that the registered buyers will be able to complete their next purchases without the need to enter their card data again.
However, this behaviour might not be compliant with PCI-DSS rules.
Merchants must NEVER store their customers’ cards data into their systems, unless they had been formally certified as PCI-DSS compliant.
In order to offer the same experience to their customers without the need to face heavy certification programs, merchants can take advantage of Tokenization feature of Gestpay, combined with IFrame solution.
With Tokenization, a merchant will be able to remotely store credit card data in Gestpay archives and receive a Token in answer; the merchant will save the received Token in its system instead of the credit card data.
For the next purchases, the merchants will send to Gestpay the Token instead of the credit card number.
Gestpay will retrieve the credit card number from its archives starting from the Token and it will complete the transaction.
Merchants will request and obtain new Tokens within the IFrame architecture, and they will use previously generated Tokens within the Server-Server architecture.
Token generation during payments in IFrame architecture
It is very simple to request and obtain a new Token during a transaction with IFrame architecture. The involved phases are the first (encryption of transaction data) and the last (decryption of Gestpay answer).
In order to request a new Token, the merchant’s system must set a value for
requestToken in the call to
Encrypt method of
WsCryptDecrypt web service. Next chapter describes which values must be used.
Here is an example
<Encrypt> <shopLogin>9000001</shopLogin> <uicCode>242</uicCode> <amount>985</amount> <shopTransactionId>34az85ord19</shopTransactionId> <!-- standard way to retreive the token --> <requestToken>MASKEDPAN</requestToken> </Encrypt>
In order to receive the Token data, the merchant’s system must read the values of
TokenExpiryYear in the response of
Decrypt method of
WsCryptDecrypt web service.
Here is an example of a Decrypt response:
<DecryptResult> <GestPayCryptDecrypt xmlns=""> <TransactionType>DECRYPT</TransactionType> <TransactionResult>OK</TransactionResult> <ShopTransactionID>34az85ord19</ShopTransactionID> <BankTransactionID>656</BankTransactionID> <AuthorizationCode>983RT4</AuthorizationCode> <Currency>242</Currency> <Amount>985.40</Amount> <!-- the token --> <TOKEN>12XYZWABCDEF3456</TOKEN> <!-- expiry month --> <TokenExpiryMonth>10</TokenExpiryMonth> <!-- expiry year --> <TokenExpiryYear>21</TokenExpiryYear> </GestPayCryptDecrypt> </DecryptResult>
Token will contain the value that the merchant’s system will use in the future.
TokenExpiryYear will not be used in the communication with Gestpay: they can be useful for the merchant in order to know till when that Token will be valid.
To get the token from
Encrypt, simply add the
MASKEDPAN value to
It’s possible to create the token in the
Encrypt method of
WsCryptDecrypt web service even if the transaction is not authorized. To achieve this result it’s necessary to use
:FORCED: before the token request:
Gestpay can manage two kinds of Tokens: standard Tokens and custom Tokens.
Standard Tokens will be made as masked card numbers.
They will start with the same 2 digits of the card they replace, and they will end with the same 4 digits of the card they replace; they will be 16 characters long. The middle part will be a string made of 10 characters that can be digits or capital letters.
The first 4 characters of this string will be always the same for each merchant (Different merchants will have a different 4 characters substring).
Card Number: 1234567890123456 Requested Token: MASKEDPAN Standard Token: 12XYZWABCDEF3456
Card Number: 3456789012345678 Requested Token: MASKEDPAN Standard Token: 34XYZWGHIJKL5678
Custom Tokens will be defined by the merchants, who will send their values to Gestpay so that Gestpay will associate them to the cards they replace.
The returned custom Token will be made by the prefix of 4 characters assigned to the merchant, followed by the value specified by the merchant.
Card Number: 1234567890123456 Requested Token: JOHN_SMITH_5533 Returned Custom Token: XYZWJOHN_SMITH_5533
Card Number: 3456789012345678 Requested Token: JACK_JONES_1234 Returned Custom Token: XYZWJACK_JONES_1234
Merchants will be able to choose which kind of Token Gestpay must provide, when they request a new Token.
This will be depend on the value of the field
When merchants request a new Token, they will send a non-empty
requestToken field to Gestpay. Gestpay will use the value of
requestToken to create the new Token.
requestToken contains the exact word
MASKEDPAN, then Gestpay will create a Standard Token.
requestToken contains any other value, then Gestpay will create a Custom Token with that value prefixed by the 4 characters string of that merchant.
Rules for Custom Tokens
Custom Tokens will be chosen and generated by merchants themselves. Gestpay will simply receive, validate, add the prefix and store them.
Merchants will be free to choose the Token they prefer, but they must respect a few rules:
- The Requested Token must be at least 10 characters long;
- The Requested Token must be at most 20 characters long;
- The Requested Token can only contain letters, digits, and underscore (
- The number of digits in the Requested Token must be at most 8;
- The Requested Tokens are not case sensitive: Gestpay will always transform them in upper case.
Using the token: request a payment
Once you have the token saved together with the expiry month and year, you can ask for a payment using the webservice
callPagamS2S performs an authorization request and, if M.O.T.O. is configured accordingly, it settles the amount.
To perform a payment you must use the
tokenValue instead of the
cardNumber and the expiry data.
Here is an example call, showing only the mandatory data:
<callPagamS2S> <shopLogin>9000002</shopLogin> <uicCode>242</uicCode><!-- euro --> <amount>24.21</amount> <shopTransactionId>MYSHOP-0001</shopTransactionId> <tokenValue>12XYZWABCDEF3456</tokenValue> </callPagamS2S>
A group of shop logins can share a set of tokens.
If a merchant belongs to a group he can use all the tokens of the other merchants of the same group. The token could be updated or deleted from each of the components of the group using the appropriate web service.
The group of merchants is defined and mantained by Gestpay customer care. When a new merchant is added to a group, he can choose to insert in the group all his previous tokens; In the same way, if a merchant leaves a group he can decide to take or leave his tokens in the group.
Tokenization feature is not automatically available to all Gestpay merchants. It must be requested and explicitly enabled by Gestpay customer care.
Recurrent payments with alternative payment systems
You can perform a recurring payment by specifying a Paypal billing agreement.
To perform recurring payments with Amazon Pay, see the relevant page.