Using Gestpay payment page

If you have already followed the super quick start guide, you should already be capable of accepting payments from your customers.

In this page we will better detail some aspects of the payment process, so that you gain full control of it.

recap: what to do in order to process payments

Description of Process Phases

A payment transaction is made up of 4 basic phases in which there are one or more communication steps. In each phase, the information necessary to process the transaction is exchanged between the various components.

Phase I: transaction data encryption

The information required for the payment is previously communicated to GestPay to be encrypted. To guarantee an optimum security level, no sensitive information is communicated in unencrypted form to the buyer’s server.

In this phase, the merchant’s server requests the encryption service from GestPay, obtaining the encrypted string that represents the transaction to process. The data that identifies a transaction and their use will be described in the API section.

Encryption can be handled using the WSCryptDecrypt WebService. The use of the web service does not require any installation on the server, but simply a call to the web service using the https protocol. The response is in the XML format.

If the merchant’s authentication checks and validation of transaction data are passed, GestPay returns the encrypted data string to the merchant’s server to be sent to the buyer’s server to continue the payment process. Otherwise, a specific error code will be returned to allow the problem detected to be identified.

Phase II: payment page call

After obtaining the encrypted data string (as described in the preceding section), the buyer’s browser is directed to the payment page on the GestPay server at the following address:

https://ecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

for test codes:

https://testecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

The call to the page will be made passing two parameters:

The payment page will acquire the parameters and verify the identity checks (parameter a must refer to a recognised merchant) and transaction data security (parameter b must correspond to the encrypted data string communicated by the merchant during the previous phase).

If the checks are passed, the payment page will be displayed to the buyer, who must enter the data required to complete the payment process.

If the checks are not passed, the payment page is not displayed and the process passes to the following phase in order to communicate the negative transaction result.

Phase III: communication of transaction result

GestPay communicates the transaction result both to the merchant and the buyer.

Response to merchant

Notification is forwarded with a server-to-server call to the page specifically configured on the merchant’s server (the notification page URL is one of the items of information that make up the merchant’s profile, configurable through the GestPay Back Office environment). Call syntax is the following:

http://<url server to server>?a=<ShopLogin>&b=<encrypted string>

The call to the page will be made passing two parameters:

If there are communication errors, GestPay will make several forwarding attempts for two days after the transaction.

The merchant will also receive a transaction result notification e-mail at the address configured in his/her profile.

In addition, the processed transaction can be viewed by accessing the GestPay Back Office environment in the Active Report section.

Response to Buyer

GestPay immediately communicates the result of the transaction. It is also possible for the buyer to download a receipt in PDF.

GestPay directs the buyer’s browser to the merchant’s server to conclude the purchasing process. The merchant must prepare two urls (and configure them in the merchant’s profile) which will be called in the event of a negative or positive response and will allow the merchant to manage communication with the buyer while maintaining the editorial style that characterises the virtual shop. The call syntax is the following:

http://<url merchant>?a=<ShopLogin>&b=<encrypted string>

If there is an anomaly in the server-to-server communication described above, GestPay displays a message to the buyer warning that there may be problems contacting the merchant’s server.

The buyer will also receive a transaction result notification e-mail at the address provided on the payment page, if indicated.

Phase IV: decryption of transaction result

GestPay communicates the transaction result through an encrypted string (parameter b of the call to the url preconfigured by the merchant). The string is initially forwarded to the merchant during server-to-server communication and makes it possible - once it has been decrypted - to update the status of the transaction recorded in the merchant’s information system. The same string is also sent from the buyer’s browser to the merchant’s server and makes it possible - once it has been decrypted - to complete the payment process.

Web pages preconfigured by the merchant for receiving the transaction result (in the case of both server-to-server communication and through the buyer’s browser) must call the GestPay server to request the decryption service and obtain the information that represents the result of the processed transaction in unencrypted form.

The request to decrypt the string received is made using WebService WSCryptDecrypt. The use of the webservice does not require any installation on the server, but simply a call to the webservice using the https protocol. The response is in the XML format.

Authentication

Server authentication of the merchant requesting encryption or decryption services is made by verifying:

If the authentication checks are not passed, a specific error will be returned, making it possible to identify the anomaly found in the authentication process.

WSCryptDecrypt Webservice

WSCryptDecrypt web service is available on production and test servers and does not require any installation on the merchant’s server.

The merchant must implement - in the page(s) of the virtual store configured to handle payments - a call to the webservice which handles requests to use the GestPay encryption service.

To request the encryption service it is necessary to call the Encrypt method.

If the encryption operation is concluded correctly (TransactionResult tag value with OK), the encrypted data string returned by GestPay will be available by reading the value of the CryptDecryptString tag.

If this is not the case, the values of the ErrorCode and ErrorDescription tag will make it possible to identify the reasons that prevented the encryption operation.

To request the decryption service it is necessary to call the Decrypt method, passing the shopLogin and CryptedString tags with the values communicated by GestPay in Phase III.

The information containing the transaction result will be available by reading the information in the XML response file corresponding to the result of the transaction.

Encrypt Method: how to obtain an encrypted string

Some of the information to communicate to GestPay is required in order to complete the payment process, while other information can be omitted without compromising the transaction process. Through the GestPay Back Office environment, merchants can define what information is required and what information is optional.

Some information that is essential to the payment process is configured as compulsory by GestPay. This attributes cannot be modified.

The complete list of the fields can be seen in WSCryptDecrypt API. Here we will show the compulsory information that must be communicated to GestPay xml using Encrypt method in order to make a transaction. The tags’ names are case sensitive.

Name Max Size Description
shopLogin 30 the shopLogin given by Gestpay
uicCode 3 Code identifying currency in which transaction amount is denominated - see Currency Codes table.
amount 9 Transaction amount. Do not insert thousands separator. Decimals, max. 2 numbers, are optional and separator is the point.
shopTransactionID 50 Identifier attributed to merchant’s transaction

These are only the mandatory fields. There are other fields that may be relevant if you want to use a specific anti-fraud system, or one of the alternative payments. Check the API for the list.

Encrypt web service returns back the following information in the xml:

Name Max Size Description
TransactionType 7 Decode the transaction type request (DECRYPT, ENCRYPT)
TransactionResult 2 Transaction result (OK/KO)
CryptDecryptString Encrypted string get by parameter set in the xml request
ErrorCode 9 Error code
ErrorDescription 255 Error description

Decrypt Method: how to obtain clear transaction result

GestPay communicates the payment transaction result to the merchant through an encrypted string (parameter b of the call to the url preconfigured by the merchant) with a set of transaction’s informations.

To Decrypt the data it is necessary to use Decrypt method passing the following parameters, the tags’ names are case sensitive:

Name Max Size Description
shopLogin 30 ShopLogin
CryptedString Encrypted string get by parameter b of the call to the url preconfigured by the merchant

The full specification of the Decrypt API is available here, the minimum returned information is:

Again, see the WSCryptDecrypt API to get further details.