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
- Sign in to Gestpay backoffice
- Get a
shopLoginand insert your server’s ip address in Gestpay
- Do a SOAP call to
Encryptmethod before the payment, and
- Redirect the user to Banca Sella’s payment page, and wait for the payment to happen
- Set up an endpoint for being contacted by Gestpay in positive / negative response.
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:
for test codes:
The call to the page will be made passing two parameters:
- a The code identifying the merchant (Shop Login)
- b The encrypted data string identifying the transaction
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:
- a the code which identifies merchant (Shop Login)
- b the encrypted data string which contains the result of the transaction
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.
Server authentication of the merchant requesting encryption or decryption services is made by verifying:
- Shop Login validity: ShopLogin parameter must correspond to a code recorded in GestPay customers’ details.
- IP address server: the calling server IP address must correspond to one of the IP addresses configured in the merchant’s profile.
- Shop Login status: the merchant’s status must be active (the merchant’s status is managed by the GestPay administrator and not directly by the merchant)
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 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
If the encryption operation is concluded correctly (
TransactionResult tag value with
the encrypted data string returned by GestPay will be available by reading the value of
If this is not the case, the values of the
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
CryptedString tags with the values communicated by GestPay in
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.
||30||the shopLogin given by Gestpay|
||3||Code identifying currency in which transaction amount is denominated - see Currency Codes table.|
||9||Transaction amount. Do not insert thousands separator. Decimals, max. 2 numbers, are optional and separator is the point.|
||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:
||7||Decode the transaction type request (
||2||Transaction result (
||…||Encrypted string get by parameter set in the xml request|
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:
||…||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.