Checkout JS SDK

Constructs a new Checkout object.

During construction, the Checkout object communicates with Nexi Checkout server APIs and also adds an iframe which embeds a checkout page. The container element on your site in which the iframe is added to, is specified when creating the payment object using the Payment API (backend).

Please note:

• You should not add the iframe yourself. The iframe is added by the Checkout object inside your container element.
• The container element cannot be located in a shadow DOM during the initialization of the checkout.
• The container element for the iframe must not be embedded in another iframe.
• Please make sure to allow to get the paymentId from the response URLs query string when initiating the Checkout, as shown here.

var checkout = new Dibs.Checkout(checkoutOptions);

Parameters

Example

The following example embeds a checkout iframe in the DOM element on your site with id 'checkout-container-div'. The display language is set to English and buttons will have slightly rounded corners:

var checkoutOptions = {
    checkoutKey: "test-checkout-key-003345054979023400345",
    paymentId : "8b464458f2524bc39fe5d31deb8bedc1",
    containerId : "checkout-container-div",
    language: "en-GB",
    theme: {
        buttonRadius: "5px"
    }
};
var checkout = new Dibs.Checkout(checkoutOptions);

The Checkout object contains the following methods.

Changes the display language on an active checkout session.

checkout.setLanguage(language);

Parameters

Changes the UI theme on an active checkout session. You can use this method to specify UI properties such as colors, fonts, and button styles. Note that this method has no effect if you have defined a custom theme in the Checkout Portal Checkout styler.

checkout.setTheme(theme);

Parameters

Sends an event with a name that will be triggered within the checkout. Currently, the only event supported is 'payment-order-finalized', where the value should be a boolean set to true. This event continues the pay flow.

checkout.send(eventName, value);

Parameters

Example

An example of usage for the event 'payment-order-finalized' is when you listen to the event 'pay-initialized'. By listening to this event, the checkout flow will not proceed the payment when your customer clicks pay unless you send the 'payment-order-finalized' event.

checkout.on('pay-initialized', function(response) {
  // Complete the desired operations such as update payment
  // ...
  checkout.send('payment-order-finalized', true);
});

When this code snippet is run, the Checkout object will continue the payment flow.

Temporarily freezes (pauses) the checkout by disabling the payment button. Call this method before updating the order items of an active checkout session. Once the order items have been updated, you should resume the checkout session by calling thawCheckout().

checkout.freezeCheckout();

Resumes a frozen checkout and triggers a reloading of the payment information. If this method is invoked after the order items has been updated, the amount will also be updated to the correct amount.

checkout.thawCheckout();

Removes all event listeners.

checkout.cleanup();

This section describes the checkout events that you can listen for and handle programmatically. Attach your event handler functions by using using the Checkout.on() method.

checkout.on(event_name, event_handler);

The event_name parameter is the name of the event. The event_handler parameter is a function that will be called when the event is triggered. The event_hander function is always passed a single object. The properties of this parameter object varies depending on the event that has been triggered. The properties of each parameter object are documented under each event below.

Triggers when your customer clicks the pay button.

checkout.on('pay-initialized', function(paymentId) {});

Parameters

Example

The following example attaches an event handler that will be called whenever the 'pay-initialized' event is triggered.

checkout.on('pay-initialized', function(paymentId) {
  // Complete the desired operations such as update payment
  // ...

  checkout.send('payment-order-finalized', true);
});

Triggers after a successful payment. This is the event that you should listen to in order to redirect your customer to a "Payment Success" page.

checkout.on('payment-completed', function(response) {});

Parameters

Example

checkout.on('payment-completed', function(response) {
  var paymentId = response['paymentId'];
  // Register a successful payment in your DB using the paymentId
  // ...

  // Redirect your customer to a "Payment success" page
  window.location = '/PaymentSuccessful';
});

Triggers whenever your customer updates address information. This is the event that you should listen to in order to update shipping cost based on your customer's location.

checkout.on('address-changed', function(address) {});

Parameters

Example

This example demonstrates how to update shipping cost whenever the customer updates the address.

checkout.on('address-changed', function(address) { 
  if (address) {                // Address has changed
    checkout.freezeCheckout();  // Freeze checkout while updating shipping cost

    var zip = address.postalCode;
    var country = address.countryCode;

    calculateShippingCost(zip, country).then(function(response) {
      // Call "update cart" method on the Payment API 
      // with the updated shipping cost.
      // ...

      checkout.thawCheckout();  // Resume checkout
    });
  }
});

Triggers whenever your customer updates contact information. This is the event that you should listen to in order to update shipping cost based on your customer's location.

checkout.on('applepay-contact-updated', function(address) {});

Parameters

Example

This example demonstrates how to update shipping cost whenever the customer updates the address.

checkout.on('applepay-contact-updated', function(address) {
if (address) {                // Address has changed

  var zip = address.postalCode;
  var country = address.countryCode;

  calculateShippingCost(zip, country).then(function(response) {
      // Call "update cart" method on the Nexi Payment API
      // with the updated shipping cost.
      // ...

      // Wait for "update cart" on the Nexi Payment API to succeed.

      // Get the new shipping cost from the response
      const newTotalAmount = response.newTotalAmount;

      // Call the method to update the Apple payment sheet with new amount
      checkout.completeApplePayShippingContactUpdate(newTotalAmount);

  });
}
});