Getting Started

Hi! This guide wants to give you a very rapid introduction about how you can integrate Gestpay in your application.

Super Quick Start Guide

In case you still don’t know what Gestpay is, Gestpay is the piece of software that will allow you to accept payments from your customers.

Gestpay can be integrated on your website in two ways:

The first steps are equal, whatever payment method you prefer.

Step 0 - Signing up

First of all, you have to register on Gestpay backoffice. To try it out Gestpay I suggest you to sign in to the Test Environment (it’s free!) and then log in.

Remember, it’s a test environment, you can mess it up as you like, there’s no real money involved.

To follow this tutorial, let’s pretend that your website responds to the URL yourshop.com .

Step 1 - Configure your Gestpay account

Once you’re in, Gestpay wants to know:

In case your server is in a cloud environment, you can use * to specify multiple addresses.

Step 2 - take the SOAP

Before you can actually redirect the user to Gestpay, you must do a SOAP call to WsCryptDecrypt.Encrypt method to initiate the communication. Click on the link to see the API.

There are two endpoints available,

https://sandbox.gestpay.net/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl
https://ecommS2S.sella.it/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl

Let’s go back to your application. Everything starts with a SOAP call to the Encrypt , asking Gestpay to process a payment with these info:

<Encrypt>
   <shopLogin>GESPAY12345</shopLogin><!-- Assigned by Gestpay backend --> 
   <uicCode>242</uicCode> <!-- code for Euro --> 
   <amount>1245.6</amount> <!-- the money you want to receive -->
   <shopTransactionId>34az85ord19</shopTransactionId> <!-- an ID generated by you -->
</Encrypt>

Gestpay will answer with:

<EncryptResult>
   <GestPayCryptDecrypt xmlns="">
   <TransactionType>ENCRYPT</TransactionType>
   <TransactionResult>OK</TransactionResult><!-- everything ok! -->
   <CryptDecryptString>2C53F1B5...</CryptDecryptString><!-- crypted string with sent info -->
   <ErrorCode>0</ErrorCode><!-- ...another way to say Ok! -->
   <ErrorDescription/>
   </GestPayCryptDecrypt>
</EncryptResult> 

With the encrypted string (2C53F1B5...) and the shopLogin you can now redirect the user to the payment page.

Now you have to choose which payment page you want to use. If you want to use Banca Sella payment page, keep reading. Otherwise, jump to using your customized payment page.

Using Banca Sella Payment Page

Using Banca Sella’s payment page is the most straightforward way to accept payments from customers. You don’t need special coding skills and you only have to redirect your users to Banca Sella’s page.

An example of the "choose payment" page. If only one payment method is selected, you will not see it.
A credit card payment page.

step 3: Redirecting the user to GESTPAY

At this point, you can redirect the user to one of these two addresses:

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

In our example, the user must be redirected to

https://sandbox.gestpay.net/pagam/pagam.aspx?a=GESPAY12345&b=2C53F1B5...

where he will be asked for his credit card data.

step 4: After the payment

If everything has gone correctly, Gestpay will communicate the outcome to the user and the merchant.

You can configure where Gestpay must redirect with the following window:

you can find this window in Configuration -> Environment -> Response Address.


When a payment is completed without errors, Gestpay will report the result to both the merchant and the user.

Returning the result to the Merchant

Gestpay will communicate to the merchant’s server an encrypted string with the result of the transaction. The url of your server must be inserted in URL Server to Server (by the way, this is optional).

Since the string is encrypted, the merchant’ server must call WsCryptDecrypt.Decrypt to decrypt Gestpay response and see the output.

At yourshop.com we have set up the page server-response.php. This page will take two parameters,a (the shopLogin) and b (the encrypted string). So Gestpay will perform a GET request to Yourshop.com:

GET http://www.yourshop.com/server-response.php?a=GESPAY12345&b=2C53F1B5...

Once the server has received a and b, he can now call the Decrypt method (from the WsCryptDecrypt webservice) and know the result of the transaction, useful for updating the database, send emails, etc.

More information on this at Using Banca Sella payment page - communication of transaction result.

Returning the result to the User

When a payment is completed without errors, Gestpay will redirect the user to the URL that is configured in URL for positive response - Similarly, if anything goes wrong, he will be redirected to the URL for negative response.

The redirection occours with two parameters:

at this point the Merchant’s Server must call WsCryptDecrypt.Decrypt again to decrypt Gestpay response and show the appropriate message to the user.

At Yourshop.com we have set up the same response page in case of positive or negative response. Of course you can differentiate the two. The user will be redirected to

http://www.yourshop.com/response.php?a=GESPAY12345&b=2C53F1B5...

response.php must be a page that will:

  • Receive two arguments, a and b.
  • Decrypt b
  • Show the result to the user (receipts, email…)

That’s it ?

Yes! go and check your backoffice page - you should see payments coming in.

You can get further details at Using Banca Sella Payment Page or continue to read what Gestpay can do for you.


Using your customized payment page

With a customized payment page, you can customize every part of the payment process and design the credit card form exactly the way you want. This means you can avoid to redirect your customers to other pages and handle everything in one page.

A graphic rapresentation of the flow. If no 3d authentication is required, only the green path is followed: it is very straightforward. However, if Gestpay requires 3d authentication for fraud prevention, then you start following the blue path. Step 1 is our starting point; step 2 has been discussed previously in this tutorial.

step 3: Import Gestpay script & security ckecks

It’s easy as adding

<script src="https://ecomm.sella.it/pagam/JavaScript/js_GestPay.js" type="text/javascript"></script> 

We can already write some Javascript to perform some security checks:

// BrowserEnabled is true if everything is OK 
if ( ! BrowserEnabled ) {
  // the browser is NOT supported
  alert('browser not supported!');
  return; 
}
// The Browser is supported!
// shopLogin and encryptedString come from Step 2... 
GestPay.CreatePaymentPage(shopLogin, encryptedString, pageLoadedCallback);

CreatePaymentPage will create an hidden iframe that will securely send credentials to Gestpay.

pageLoadedCallback is a function that will be fired after the creation of the hidden iframe. Let’s see it:

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

  // SPOILER -- we'll talk later about this. 
  if (PARes) {
    var transKey = getCookie('transkey'); // use your preferred method to get cookies 
    handle3Dsecurity(PARes, transkey);
  }
} 

step 4: create the HTML form

Create the html markup to show the credit card form:

<form name="myCCForm" action="" method="post" OnSubmit="return checkCC();">
  <fieldset>
    <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=""/>
  </fieldset> 
  <fieldset>
    <input type="submit" name="submit" value="Send Payment" id="submit" />
  </fieldset>
</form>

As you can see, the submit action must not send data to the server. This is crucial to adhere with PCI requirements. You should never see credit card numbers, never ever.

Step 5 - Send the payment

When the user submits the form, the checkCC() function will be called. Let’s see how we could implement this:

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

Handling 3D Security

Gestpay may ask, to reduce the risk of fraud, to authenticate the card against Verified By Visa, Mastercard SecureCode or Amex SafeKey.

To determine if this is the case, let’s analyze ErrorCode field:

ErrorCode description
0 payment completed without errors!
8006 we must handle 3DSecurity; user must validate his credit card against Visa, or Mastercard, or what else. This does not happen always, only when the system believes it is necessary.
any other value another type of error has occurred, unable to continue the payment.

Referring to the flow diagram, we are now considering step 6.

what happens when the ErrorCode is 8006? In this phase, we must redirect the user to Gestpay 3d secure check page, which is

Redirect the user sending the shopLogin, the VBVRisp, and a url to where the user must be redirected.

In our code it would be something like this:

var paymentCompletedCallback = function(Result) { 
  if (Result.ErrorCode != 0) {
    if (Result.ErrorCode == 8006) { // 8006 : Card holder authorization required
      
      //Get the TransKey 
      //NOTE: you have to store this value somewhere (for example, in a cookie) 
      //for further use. After the redirect, you'll need this. 
      var TransKey = document.cookie = "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
      redirect(shopLogin, VBVRisp, your_url);

      ...
    } else {
      //Call failed for other errors  
      //.... place here error handle code...
    } 
  } else {
    //Call went good. proceed to decrypt the Result.EncryptedResponse property
  }
}

After 3d secure happens succesfully, Gestpay will redirect to the page you have configured. Now we have to know that we have successfully authenticated via the PARES parameter. Here is the code (Recall the code in step 2):

function pageLoadedCallback(result) {
  if(Result.ErrorCode != 10){  
    // An error has occurred
    return; 
  }
  ...
  //if 3d auth is successful, a parameter PaRes will be passed 
  // to this page (via POST). You can get it in some way 

  // e.g. in php: 
  var PaRes = <?= $_REQUEST["PaRes"]; ?>

  if (PaRes) {
    var transKey = getCookie('transkey'); // use your preferred method to get cookies 
    handle3Dsecurity(PaRes, transkey);
  }
} 

if the two variables PARES and transKey are defined, we can complete the payment:


function handle3Dsecurity(PaRes, transkey) {

  GestPay.SendPayment({
    'TransKey':'//PLACE HERE THE TRANSKEY VALUE',
    'PARes':'//PLACE HERE THE PARES VALUE'
  },
  paymentSuccededCallback);
} 

function paymentSuccededCallback(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;
  } 
} 

Now that you have the responseString, you can call the WSCryptDecrypt’s Decrypt method and verify that everything has gone good. The same outcome will be sent to your server, too.

That’s it! For further reading about customizing your payment page, go to creating your custom payment page.