Embedd Checkout

On this page you will find information about How to embed the Checkout form, How to Update items and How to handle Callbacks necessary for the checkout to work.

Showing the Checkout form

The step after intializePayment where the session is started and the paymentkey is defined is to display the checkout application.

Include Avarda javascript into your web page in the checkout page.

// Test environment:
// Synchronous version
<script src="https://stage.avarda.org/CheckOut2/Scripts/CheckOutClient.js"></script>
 
// Asynchronous version
<script src="https://stage.avarda.org/CheckOut2/Scripts/CheckOutClient.js" async></script>
 
// Production environment:
// Synchronous version
<script src="https://online.avarda.org/CheckOut2/Scripts/CheckOutClient.js"></script>
 
// Asynchronous version
<script src="https://online.avarda.org/CheckOut2/Scripts/CheckOutClient.js" async></script>

Important: JavaScript URL needs to correspond to the desired environment.

The synchronous variant is easier to work with since the page execution is blocked until the script is loaded from given URL. On the other hand, it might have a negative impact on user experience. For that reason, you might want to consider to load the script asynchronously by adding the async attribute (as shown above). The downside of this approach is that the script will not be available immediately as the script execution is not blocked while the script is loading. You code will need to make sure that it has been loaded properly before calling it.

Define where you want the checkout to be loaded on your web page

Add a <div> on your website in which you want the checkout to be placed.

Define javascript option parameters and call init

After the script has been loaded, you can call the AvardaCheckOutClient.init method, which renders the Check-Out form. The method expects the Purchase ID acquired in previous step, ID of the DOM element inside which the Check-Out form should be shown and callback function that that gets called after the payment has been completed (successfully or not).

<!DOCTYPE html>
<html>
  <head>
    <script src="https://stage.avarda.org/CheckOut2/Scripts/CheckOutClient.js"></script>
    <script>
      var options = {
        // ID of the <div> inside which to render the form
        divId: 'checkOutDiv',
        // The Purchase ID obtained in the previous step
        purchaseId: '489ea341e23941089e6d0378c708512a',
        // What to do once the result is available
        done: function (purchaseId) {
          window.location.href = '/done.php?purchaseId=' + purchaseId;
        },
        // Where to return if we have to redirect the customer out of your website temporarily
        callbackUrl:
          'https://my-shop.com/checkout.php?purchaseId=489ea341e23941089e6d0378c708512a&callback=1',
      };
      AvardaCheckOutClient.init(options);
    </script>
  </head>
  <body>
    <h1>Contoso E-shop</h1>
    s
    <div id="checkOutDiv"></div>
  </body>
</html>

In the example above, the form gets rendered in a DOM element with ID checkOutDiv and user gets redirected to done.php page after the payment has been completed.

The done Callback Function

Checkout will call the done function provided by merchant when the payment session has ended (successfully or not).

Please note that there is no argument in the done function telling whether the payment has been successful or not. The reason is that such information could not be trusted anyway, since it comes from the client-side JavaScript that the end customer could manipulate easily. For this reason, the done.php page is expected to verify the actual purchase state by calling the GetPaymentStatus API method.

init Function Arguments

A complete list of properties that can be used to set-up the form is described in the table below:

Property	Data type	Default Value	Description
`divId`	String		ID of the `div` inside which to render the Check-Out form.
`purchaseId`	String		The Purchase ID acquired during the session negotiation.
`done`	String	An empty function	A callback function that gets called when the payment has been completed (successfully or not). Altrough this parameter technically isn’t required, the integration would be useless without it.
`customCssUrl`	String	null	A fully-qualified URL of the custom CSS file to use. Relative URLs will not work. See Custom CSS Styles for details.
`replaceDefaultCss`	Boolean	false	When false, the custom styles will be used together with the default styles. If true, only the custom styles will be used. See Custom CSS Styles for details. If the `customCssUrl` is not set, this property has no effect.
`beforeSubmit`	Function	null	A function that, if defined, is called right before the Check-Out form is submitted. If it returns `false`, the submit gets canceled. It is useful e.g. in cases when there’s another form on the page that hosts the Check-Out iframe that must also be valid before the Check-Out form can be submitted.
`beforeCompleteHook`	Function	null	A function that, if defined, is called right before the Check-Out is completed. This function must call continue or cancel function. More details.
`updateDeliveryAddressHook`	Function	null	A function that, if defined, is called right after Delivery address is updated by custommer. This function must call continue or cancel function. More details. More details.
`callbackUrl`	String or a function that returns a string	nul	An URL where to return after the customer has been redirected to a 3rd party website (such as when paying by a card). It can be defined wither as an URL or a function without any arguments that returns a string.

Important! Depending on various aspects (such as whether the invoicing address that customer filled-in into the form differs from delivery address), the form may or may not redirect the browser to a 3rd party website such as Signicat in order to verify user’s identity. The 3rd party service eventually makes a redirect back to the original page. Therefore, the URL of the web page that hosts the check-out form must be callable repeatedly. When redirecting back to the original page that hosted the Check-Out form a callback=1 parameter is added to the original URL.

Remarks

The form layout may vary from partner to partner depending on parameters such as the partner’s country, enabled payment methods etc.
The client script doesn’t require any external library such as jQuery.
It’s OK to call the init function without waiting for the document.ready event, as shown in the example. The client script does wait for it internally if needed.
In the current implementation, the client script renders an iframe inside a specified div and places the whole form inside it. The reason why there’s this one extra container is that it gives us more flexibility. If we ever need to change the client script in a way that it adds something else next to the iframe element, no adjustment is needed on the partner side.
The client script adjusts the height of the iframe automatically according to its contents so that it never has to scroll.

Update items

While the checkout is active it is possible to update the items and price if the shopping cart changes.

// example of updating purchase
 
var updatedPurchase =
    {
      "PurchaseId": "19ac0d1ee909c302d212b4324d9194b5",
      "Price": 100.00,
      "Items": [
        {
          "Description": "Blue ball",
          "Notes": null,
          "Amount": 1.00,
          "TaxCode":12,
          "TaxAmount":"TaxAmount"
        }
      ]
    }
 
    $.ajax({
            url: /CheckOut2Api/UpdateItems
            data: updatedPurchase,
            method: "POST"
        })
        .done(() => {
            AvardaCheckOutClient.updateItems();
        });

How to get started Callback