How to request a token

With Tokenization a merchant will be able to remotely store credit card data in Fabrick Payment Orchestra archives and receive back a Token; 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 Fabrick Payment Orchestra the Token instead of the credit card number.

Fabrick Payment Orchestra will retrieve the credit card number from the archives, starting from the Token, and will complete the transaction.

This operation provides the generation of a new Token during a transaction passing the requestToken field, so they will obtain a Token in response.

The correct WSs2s web service method to use for this purpose is callRequestTokens2S.

A group of merchants can share a set of tokens.

So if a merchant belongs to a group, it can use all the tokens of the other merchants of the same group.

Merchants cannot directly define and manage groups. Groups are managed only by Banca Sella operators, who will take care of the requests coming from merchants.

The available options are:

• Adding a merchant to a group, and with them, all the tokens previously created by the merchant

• Adding a merchant to a group without the tokens previously created by the merchant, but only those created since after joining the group

• Removing a merchant from a group and remove all their tokens from the group

• Removing a merchant from a group but leaving their tokens in the group; the new token created by the merchant since the exclusion from the group will be accessible only by that merchant

This is the mandatory information to send to Fabrick Payment Orchestra:

• shopLogin (merchant code)

• requestToken (MASKEDPAN for a Standard Token, any other value for Custom Token)

• cardNumber (credit card account number)

• expiryMonth (card expiration month)

• expiryYear (card expiration Year)

• cvv (String containing the Card Verification Value printed on the credit card, as specified in CVV field management )

• withAuth flag that indicates if the request should also try to authorize the transaction.

The callRequestTokens2S method sends to Fabrick Payment Orchestra all previously assigned data, if the flag withAuth is set to Y then uses this data is used to make a transaction request without affecting the account and returns the result of the operation; otherwise, only the information about the card is given back.

After the callRequestTokens2S request has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:

• First, it is possible to use the TransactionResult method, which will return the string OK if the check has been performed or the string KO if not. In the fields TransactionErrorCode and TransactionErrorDescription there is a detailed information in case of error.

• AuthorizationResult field which will return the string OK if the transaction was authorised or the string KO if the transaction was not authorised

• If AuthorizationResult returns the string KO, then it is possible to know whether the failure was due to a negative response from the credit card network, using the AuthorizationErrorCode method:

  • If AuthorizationErrorCode returns a value, which is <> 0, the transaction was denied due to technical problems; the value returned will vary according to the specific reason for the failure. The AuthorizationErrorDescription method will return a description of the reason for the failure (in the language set within the Back Office environment).

  • If AuthorizationErrorCode returns the value 0, the transaction did not fail due to technical problems. The description of the error will be shown in the language set within the Back Office environment by using the AuthorizationErrorDescription method.

• If AuthorizationResult returns the value OK, the transaction was authorised and the card is considered valid.

See the description for other fields in the API section.