Creating your custom payment page

Gestpay iFrame payment page allows merchants to process online credit card transactions with an hidden payment page within an iFrame in the shop checkout page.

The adoption of the GestPay iFrame payment page will leave to the merchant the full control of the form design, the credit card data will be sent by the merchant checkout form to a hidden payment page (which will be on the GestPay servers) via javascript.

This solution will free the merchant by the need to comply with PCI-DSS Security Standards.

Tokenization and Iframe solutions are available to Enterprise users.

Step 0: sign up to Gestpay

… we assume you have already done this, didn’t you? Configure your backoffice by reading the Sign up to Gestpay and then configure your Gestpay account properly.

Now the real fun begins.

Step 1: Encrypting the request

This is pretty much the same of the take the SOAP.

Basically, you Encrypt the transaction information with your shopLogin, uicCode (the currency code), amount, and a shopTransactionId (an identifier that you give to your transaction).

Gestpay will answer with at least two parameters:

Here is an example. The merchant’s server communicates the information of the transaction, setting the values of WSCryptDecrypt’s Encrypt method like this:


GestPay authenticates the calling server and validates the information that characterises the transaction. If the controls are passed, it returns an encrypted string to GestPay:

  <GestPayCryptDecrypt xmlns="">

Step 2: setup javascript and HTML

After obtaining the encrypted data string (as described in the preceding section), the buyer’s browser will be redirected to the merchant checkout page which will include a remote javascript file from GestPay’s servers:

<script src="" type="text/javascript"></script> 

The script will automatically perform a browser compatibility check to ensure that the HTML 5 postmessage function, which will be used to exchange data, is supported.

The result of the check will be the boolean value of the variable BrowserEnabled:

If (BrowserEnabled){
   // The Browser is supported!
   // Proceed to create the payment page
   // the browser is NOT supported
   // Place here error handler code 

To load the hidden iFrame page, the checkout page must call the Javascript function GestPay.CreatePaymentPage passing the Merchant code, the Encrypted string and a callback object needed to read the security checks results.

If (BrowserEnabled) {
   // The Browser is supported!
} else {
   // the browser is NOT supported

The function will create an hidden iFrame into the body element and will load the payment page passing the merchant code and the generated encrypted string from the previous phase.

  style="position:absolute;top:0;left:0;width:0;height:0;visibility:hidden" >

When the payment page is called, it will perform the security checks needed and will fire the result in the result object.

var paymentPageLoadedCallback = function(result) {
  if(Result.ErrorCode != 10){ // 10 means no security errors 
    //An error has occurred
    //result.ErrorCode will return the Error occurred 
    //Result.ErrorDescription will return the Error Description 
    //.... place here error handle code...
  } else {
   //the iFrame is correctly created and the payment page is loaded;
   // the user can proceed to insert the credit card data.

If the browser compatibility check fails the iFrame will not be created and the payment page will not be loaded!

You can see the supported browsers in the Software Requirements section.

Step 3 - Send the credit card data

To send the credit card data to the hidden iFrame, the checkout page will assign a function to the OnSubmit event of the credit card form. This function will retrieve the credit card data and will call the GestPay.SendPayment function, providing an array with the credit card number (CC), the expiration month (EXPMM) and the expiration year (EXPYY), the CVV (CVV2) if enabled, and a callBack function.

Here is an example form:

<form name="myCCForm" action="" method="post" OnSubmit="return checkCC();">
    <legend>Insert Credit Card Data</legend>
    <label for="CC">Credit Card Number</label>
    <input type="text" name="CC" value="" autocomplete="off" id="CC" /> 
    <label for="ExpMM">Expiry Month</label>
    <input type="text" name="ExpMM" id="ExpMM" value=""/>
    <label for="ExpYY">Expiry Year</label>
    <input type="text" name="ExpYY" id="ExpYY" value=""/>
    <label for="CVV2">CVV2 / 4DBC</label>
    <input type="text" name="CVV2" id="CVV2" value=""/>
    <label for="BuyerName">Buyer's name</label>
    <input type="text" name="BuyerName" id="BuyerName" value=""/>
    <label for="BuyerEmail">Buyer's email</label>
    <input type="text" name="BuyerEmail" id="BuyerEmail" value=""/>
    <input type="submit" name="submit" value="Send Payment" id="submit" />

And the javascript checkCC function:

function CheckCC(){
  GestPay.SendPayment ({
    CC : document.getElementById('CC').value,
    EXPMM : document.getElementById('ExpMM').value, 
    EXPYY : document.getElementById('ExpYY').value, 
    CVV2 : document.getElementById('CVV2').value,
    BuyerName : document.getElementById('BuyerName').value,
    BuyerEmail : document.getElementById('BuyerEmail').value
  }, paymentCompletedCallback); 
  return false;

To free the Shop from the need to comply with PCI-DSS Security standard, the OnSubmit event of the Credit card form must avoid to postback the Credit Card data to the checkout page!

Step 4 - Transaction results

Gestpay will send the transaction result as javascript object and as notification which will be forwarded with a server-to-server call to the page properly set on merchant’s server (the notification page can be set in the URL Server to Server Response feature of the Configuration > Environment section of the Merchant Back Office environment).

How to deal with 3D transactions (Verified by Visa, Mastercard SecurCode, etc)

Transactions made by 3D credit cards require the cardholder authentication. The buyer will be redirected to the card issuer web site and will have to fill a password which was released to him by the issuer itself. In case the authentication process ends up positively the transaction may end-up and generate a positive or negative result according to the reply from the credit card companies.

If the card is recognized as 3D the outcome of the request is a specific error code (8006) which is readable by means of the ErrorCode property of the Result object. The error description (Verified By Visa) will be readable by means of the ErrorDescription property of the Result object.

In this phase additional info are showed, that are necessary during the payment process and are specific to 3D transactions. In particular it is necessary to acquire the transaction id readable by means of the TransKey property of the Result object and a ciphered string to be used during the subsequent phase readable by means of the VbVRisp property of the Result object.

var paymentCompletedCallback = function(Result) { 
  if (Result.ErrorCode != 0) {
    if (Result.ErrorCode == 8006) { 
      //3D Transaction - Card holder authorization required
      //Get the TransKey 
      //NOTE: you have to store this value somewhere for further use
      // after the redirect, you'll need this. 
      var TransKey = Result.TransKey;
      //Get the VBVRisp; we will need it soon ! 
      var VBVRisp = Result.VBVRisp;
      //place here the code to redirect the card holder to the authentication website
    } else {
      //Call failed for other errors  
      //.... place here error handle code...
  } else {
    //Call went good, proceed to decrypt the Result.EncryptedResponse property

Cardholder Authentication

If the credit card results enrolled, it is a prerequisite to allow the buyer authenticating himself in front of his credit card Issuer. The buyer’s browser has to be redirected to a dedicated GestPay’s page which will act as an interface for the authentication and will address the buyer to the Issuer’s site giving him all necessary info for the authentication.

The page to recall has the following URL:

The page is to be called through the following 3 parameters:

Parameter Description
a shop_login
b a ciphered string acquired in the previous phase through the Result.VbVRisp property of the Result object
c URL on the merchant web site to which the buyer must be redirected after the authentication procedure

At the end of the authentication process the buyer will be redirected on the merchant site to the URL specified as redirection parameter c.

After the redirection, the merchant’s page will recall the Gestpay.SendPayment() function with two parameters:

PaRes is a ciphered string containing the authentication result, which must be acquired by the merchant and forwarded to GestPay during the following phase.

Ensure that PaRes doesn’t contain any newline characters, like ASCII character 10 (new line) or 13 (carriage return).

Transaction end

Once the buyer lands to the merchant website after the authentication, we have all the necessary info to end the transaction. A new authorization request must occur using the GestPay.SendPayment method.

Before using such method, it is necessary to include the GestPay javascript and call the Javascript function GestPay.CreatePaymentPage passing the Merchant code and the Encrypted string created before the first authorization request.

Once the hidden iFrame is created the page can proceed to send the new authorization request through the GestPay.SendPayment method, passing an array containing the TransKey value (TransKey), the Pares value (PARes) and the CallBack object to handle the asynchronous response and retrieve the encrypted string with the transaction results.


LocalObj.CallBack = function (Result) { 
  if (Result.ErrorCode != 0){
    //Call failed an error has occurred
    //.... place here error handle code...
  } else {
    //Call went good
    //place here the code to retreive the encrypted string
    var responseString = Result.EncryptedResponse;

Response to the 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:

The page residing on the merchant’s server must have the html tags <HTML></HTML> in the source.

If Gestpay doesn’t receive a response with a 200 status code from the merchant’s website, it will retry twice for the next 24 hours at 6:00 and at 18:00.

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.

Fallback to default payment page call

GestPay will let the shop to redirect the card holder to the default payment page as alternative to the iFrame solution in case the browser did not support the iFrame solution.

The page will resides on the GestPay servers and let the card holder to insert the credit card data without the merchant can see or store them.

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

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

Communication of transaction result

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

Response to Buyer

GestPay immediately communicates the result of the transaction by displaying a “virtual receipt” showing essential transaction data.

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 directing him/her to the merchant’s server to conclude the purchasing process. In this situation, the buyer receives a notification from GestPay about the transaction result and is invited, if there are anomalies, to contact the merchant by other means (e.g. e-mail) to conclude the purchasing process.

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

Transaction result decryption

GestPay notifies transaction result through an encrypted string (parameter b of the call to the url preset by merchant or EncryptedResponse property of the javascript object Result). The string allows, once it’s decoded, updating the state of the transaction registered in the merchant’s informative system.

Web pages preset by the merchant for receiving the transaction result (in the case of both server-to-server communication and through the Result Javascript Object) must call the GestPay server to request the decryption service and obtain the result of the processed transaction in unencrypted form.

The request to decrypt the string received can be made through the use of the webservice. It 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 to Server 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.