How Do I Integrate the Payment Gateway?

This article provides you with every single necessary step to integrate a new version of the GoPay payment gateway. You can find all the essential information in this article, so that you can integrate the payment gateway to your marketplace as fast as possible.

OAuth

The payment gateway interface uses REST API in order to communicate. The communication uses the HTTPS requests. OAuth 2.0, which is an open security standard for authorization, provides with a secure access to API.

The OAuth protocol enables you to obtain different levels of authorized access to API functions. The communication uses the so-called tokens. At the beginning of the integration process, we send you your credentials, called Client ID and Client Secret, which are necessary to generate the tokens.

Our tip: If you haven’t received your credentials yet, please contact our integration support via integrace@gopay.cz

The very first step, before the payment is created, is to generate the token. Consequently, you will send this token together with every API request. The token is passed in the request header.

You can get the token by making an API call to /api/oauth2/token URL. The token can be created in two scopes of authorization: the first one is payment-create which you only use to create payments, and the second is payment-all which provides with all of the other payment operations. The token you obtained expires in 30 minutes and it must be passed in the header of every API request.

Our tip: The address for testing API in your sandbox environment is: https://gw.sandbox.gopay.com/api/

API in your production environment is available at: https://gate.gopay.cz/api/

Creating the payment

In order to authorize a payment you need to create it. The payment is created by making a GoPay REST API call to /api/payments/payment URL. While the payment is being created, all the parameters are specified, for example: price, currency, accepted payment methods, pre-selected payment method, order items, payment gateway language, notification address and return address. You can find further information in description of a standard payment.

In order to make your request successful, the header must contain the token that you created before. This token allows us to perform the required operation.

The JSON object is returned as a response to your calling with all the details about the payment. The most important parameter is id which is a unique identification number for the payment in the GoPay payment system. You should save the payment ID in your database, next to the order associated with. ID enables both: the http notification and the return from the payment gateway to be successfuly processed. The gw_url is another important parameter which you will use to initialize the payment gateway as described in the next step.

Initializing the payment gateway

You can initialize either the inline payment gateway, or the redirect payment gateway. The inline payment gateway opens a payment form in the layer over the interface of your marketplace. The redirect version requires the redirecting step, so that the payment process takes place at the gopay.cz domain. You can try out both the versions on our demo e-shop: https://www.goshop.cz. You can also choose from 2 options of initializing the payment gateway: a pre-created payment, or javascript initializing. The pre-created payment is suitable for a multi-step cart, whereas initializing the payment gateway with javascript is suitable for a 1-click payment.

Pre-created payment

This option is suitable for a multi-step shopping cart. When the customer confirms their order on the server, the payment is created. Then the customer can see a form - its target is the gw_url, which initializes the payment gateway, either the inline option, or redirect option. When the form is submitted, the payment gateway is initialized.

Initializing with javascript

The second option initializes the payment gateway with a javascript calling. When the customer confirms the order, your server receives an ajax request. The server has to get the access token in order to create the payment. The response is a gw_url of the payment created. Once you have the gw_url, you can initialize the payment gateway with javascript:

_gopay.checkout({gatewayUrl: url, inline: true});

The method is parameterized by the object that contains a gatewayURL of the created payment, and the inline parameter defining which option of the payment gateway (inline, or redirect) will be initialized. In order to use the _gopay.checkout method you need to include the GoPay Javascript API:

Sandbox​

<script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js">

Production environment

<script type="text/javascript" src="https://gate.gopay.cz/gp-gw/js/embed.js">

Below can be find an example of initializing the payment gateway with javascript:

<body>
<script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js"></script>
<h3>Inline-gw</h3>
<script type="text/javascript">
   $( document ).ready(function() {
       //event handler for making the payment
       $( '#payment-invoke-checkout' ).on( 'click', function( event ) {
           event.preventDefault();
           postParams = $('#payment-container').serialize();
           //payment is created by asynchronous request to server-side script (first 'access token', then 'payment create')
           $.ajax({
               url: '/eshop/create-payment',
               type: 'POST',
               data: postParams

           }).done(function( inlineCreateResult ) {
               //there should be the gw_url in the response (gw_url is obtained )
               //the embed payment gateway is initialized with .js API
               _gopay.checkout({gatewayUrl: inlineCreateResult.gw_url, inline: true}, function(checkoutResult) {

                  //the callback can catch the embed closing
                  //the parameter of the callback is the checkoutResult object, which contains id and url (return-url)
                  //!!but making the return from the purchasing process to the returnURL must be taken into account!! (payment buttons)

                  //make a payment status call and display the result
                  $.ajax({
                    url: '/eshop/get-payment-status',
                    type: 'POST',
                    data: {inlineGetState: null, eshopGoId: $(actionBean.eshop.eshopGoId), paymentId: checkoutResult.id}

                  }).done(function( inlineGetStateResult ) {
                      $("#payment-container").prepend("<p style='background-color:yellow;padding:8px;border:solid black 1px'>Stav platby: " + inlineGetStateResult.state + "<br><br>URL: <a href='" + checkoutResult.url + "'>" + checkoutResult.url + "</a></p>")
                  });
               });

           }).error(function(data) {
               alert('error' + data);
           });
        });
    });
</script>

<form id="payment-container" action="/eshop/create-payment">
   <input type="hidden" name="order_id" value="123"/>
   <button id="payment-invoke-checkout" type="submit" name="pay">Pay</button>
</form>
</body>

Returning from the payment gateway

After the payment is created (or canceled), the customer returns back to the marketplace. There are 2 ways to make the return. The first one is redirecting to the return_url which is defined at the time of creating the payment. The second option is the callback function which is passed as another parameter for _gopay.checkout. There’s no redirecting process in this case. The callback function can only be performed when the customer hasn’t been redirected out of the payment gateway after making the payment - otherwise there’s a standard return_url redirect.

Returning from the payment gateway with a return_url

When the payment is created, the return_url parameter is passed in a callback object. After the payment is made, the customer is returned to that URL. There’s a ?id=<id_platby> GET parameter connected next to the return_url. With that id, you can easily identify the customer. It’s also necessary for you to make a payment status call with the id and provide the customer with display of the current payment status.

Returning from the payment gateway with a callback function

There’s a second option, when you don’t have to make redirecting to the return_url. When there are payment methods which don’t require redirecting from the payment gateway (e.g. a card payment), the payment gateway can call the function which you define and you will pass that function together with a _gopay.checkout function while initializing the payment gateway. That initializing can look like as follows:

_gopay.checkout({gatewayUrl: inlineCreateResult.url, inline: true}, function(checkoutResult) { alert(checkoutResult);})

When the payment is made the function that you defined will be called. We suggest you make an ajax request to your server which will check the payment status. Based on the payment status, display this payment detail to your customer.

Although you use the callback function, the return_url still matters. Some of the payment methods, such as an online payment button, require redirecting out of the payment gateway, so that you can’t use the callback function. There’s always a return to the return_url in such situations.

Notifications

Notifications automatically inform the marketplace about any update of the payment status.

When the payment is created, the notification_url parameter is passed as a part of the callback object. The notification url receives an asynchronous HTTP/GET notification whenever the payment status is updated. The format of the notification is http://eshop.tld?id=<id_platby>. The GET id parameter enables you to search for the particular order and you can make a payment status call in order to find out the current payment status. You can save the status in your database next to the payment associated with that order, or you can perform specific operations, such as make a payment.

SSL Certificate

In order to use the inline payment gateway on your website, it’s necessary for you to have a SSL certificate, issued by a certificate authority. If the website doesn’t have such a certificate (there’s no green part in the browser address bar), the customer is redirected from your website to the secure environment of the GoPay websites, see bellow.

The redirect option offers an alternative solution. The customer gets redirected from your website to the secure environment of the GoPay payment gateway. If you run a smaller e-shop and you don’t want to use a SSL certificate, then we suggest you use the redirect option of the payment gateway.