open menu
axerve docs
Payments/Recurring payments/Handling subscriptions

Handling subscriptions 

SOAP

Tokenization means the replacement of a sensitive piece of information (i.e.: credit card number) with a non-sensitive one, called Token.

Tokenization is used within Axerve Ecommerce Solutions 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 their customers to register in their online shop, often save the customer’s credit card data in their system.

This has many advantages, the first one is that the registered buyers will be able to complete their next purchases without the need to enter their card data again.

However, this might not be compliant with PCI-DSS rules.

warning

Merchants must NEVER store their customers’ cards data in 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 processes, merchants can take advantage of Tokenization feature of Axerve Ecommerce Solutions, combined with iFrame solution.

With Tokenization, a merchant will be able to remotely store credit card data in Axerve Ecommerce Solutions archives and receive a Token in response; the merchant will save the received Token in the system instead of the credit card data.

For the next purchases, the merchants will send to Axerve Ecommerce Solutions the Token instead of the credit card number.

Axerve Ecommerce Solutions will retrieve the credit card number from the archives starting from the Token and 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 Axerve Ecommerce Solutions 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's data) and the last (decryption of Axerve Ecommerce Solutions response).

In order to request a new Token, the merchant’s system must set a value for requestToken in the request to Encryptapi link method of WsCryptDecrypt web service. Next chapter describes which values must be used.

Here is an example of the Encrypt request:

copy
1<Encrypt> 
2  <shopLogin>9000001</shopLogin> 
3  <uicCode>242</uicCode> 
4  <amount>985</amount> 
5  <shopTransactionId>34az85ord19</shopTransactionId> 
6  <!-- standard way to retreive the token --> 
7  <requestToken>MASKEDPAN</requestToken> 
8</Encrypt> 

In order to receive the Token data, the merchant’s system must read the values of TokenTokenExpiryMonth and TokenExpiryYear in the response of Decryptapi link method of WsCryptDecrypt web service.

Here is an example of a Decrypt response:

copy
1<DecryptResult>
2  <GestPayCryptDecrypt xmlns="">
3    <TransactionType>DECRYPT</TransactionType>
4    <TransactionResult>OK</TransactionResult>
5    <ShopTransactionID>34az85ord19</ShopTransactionID>
6    <BankTransactionID>656</BankTransactionID>
7    <AuthorizationCode>983RT4</AuthorizationCode>
8    <Currency>242</Currency>
9    <Amount>985.40</Amount>
10    <TOKEN>12XYZWABCDEF3456</TOKEN>
11    <TokenExpiryMonth>10</TokenExpiryMonth>
12    <TokenExpiryYear>21</TokenExpiryYear>
13  </GestPayCryptDecrypt>
14</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 Axerve Ecommerce Solutions: 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

Axerve Ecommerce Solutions can manage two kinds of Tokens: standard Tokens and custom Tokens.

Standard Tokens will be composed of 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; and 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
Requested Token
Standard Token

1234567890123456

MASKEDPAN

12XYZWABCDEF3456

3456789012345678

MASKEDPAN

34XYZWGHIJKL5678

Custom Tokens

Custom Tokens will be defined by the merchants, who will send their values to Axerve Ecommerce Solutions so that they will be associated with 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
Requested Token
Returned Custom Token

1234567890123456

JOHN_SMITH_5533

XYZWJOHN_SMITH_5533

3456789012345678

JACK_JONES_1234

XYZWJACK_JONES_1234

Merchants will be able to choose which kind of Token Axerve Ecommerce Solutions 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 Axerve Ecommerce Solutions. Thrn the value requestToken will be used to create a new Token.

If requestToken contains the exact word MASKEDPAN, then Axerve Ecommerce Solutions will create a Standard Token.

If requestToken contains any other value, then Axerve Ecommerce Solutions 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. Axerve Ecommerce Solutions 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: Axerve Ecommerce Solutions will always convert 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 callPagamS2Sapi link.

callPagamS2S performs an authorization request and, if MOTO is configured accordingly, it settles the amount.

To perform a payment you must use the tokenValue instead of the cardNumber and the expiry date.

Here is an example call, showing only the mandatory data:

copy
1<callPagamS2S>
2  <shopLogin>9000002</shopLogin>
3  <uicCode>242</uicCode><!-- euro -->
4  <amount>24.21</amount>
5  <shopTransactionId>MYSHOP-0001</shopTransactionId>
6  <tokenValue>12XYZWABCDEF3456</tokenValue>
7</callPagamS2S>

Sharing tokens

A group of shop logins can share a set of tokens.

If a merchant belongs to a group they 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 maintained by Axerve's customer care. When a new merchant is added to a group, they can choose to insert in the group all the previous tokens. In the same way, if a merchant leaves a group they can decide to take or leave their tokens in the group.

default

Tokenization feature is not automatically available to all Axerve Ecommerce Solutions merchants. It must be requested and explicitly enabled by Axerve's customer care.

Recurring payments with alternative payment systems

Paypal

You can perform a recurring payments by first checking a Paypal billing agreement.

Amazon Pay

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

Previous
prevRecurring payments and Negative Option Billing on MasterCard cards
Next
Axerve Pay by Linknext