Handling Subscriptions

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.

Therefore it is advisable for merchants, before they begin to work with Gestpay Tokens, to read both IFrame and Server-to-Server sections.

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 request:

<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 Token, TokenExpiryMonth and 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. TokenExpiryMonth and 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 requestToken:

<requestToken>MASKEDPAN</requestToken>

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:

<requestToken>:FORCED:MASKEDPAN</requestToken>

Token Values

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).

Example:

Card Number:     1234567890123456
Requested Token: MASKEDPAN
Standard Token:  12XYZWABCDEF3456

Card Number:     3456789012345678
Requested Token: MASKEDPAN
Standard Token:  34XYZWGHIJKL5678

Custom Tokens

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.

Example:

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 requestToken.

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.

If requestToken contains the exact word MASKEDPAN, then Gestpay will create a Standard Token.

If 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:

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.

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>

Sharing tokens

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

Paypal

You can perform a recurring payment by specifying a Paypal billing agreement.

Amazon Pay

To perform recurring payments with Amazon Pay, see the relevant page.