Hosted Payments Lightbox

The Hosted Payments Lightbox opens a modal window containing a payment form to collect information from a customer checking out on the merchant's site.

The hpp-url is the URL for the environment you are currently using.​

  • Sandbox: https://uat.hpp.converge.eu.elavonaws.com
  • Production: https://hpp.eu.convergepay.com

In addition to the hpp-url, the form will need a Session ID. This is obtained from creating a payment session. See Server-Side Scripting for more information.

The Hosted Payments Page supports most modern browsers.
The Hosted Payments Page does not support Internet Explorer and Microsoft Edge.

Your Merchant Alias and Public API Key can be safely stored on-page for your website. However, you will need to generate a Session ID from a payment session request and add that information into the template URL before it will work correctly. For more information, see the Payment Sessions resource.

Configuring the HPP Type and Origin URL

When creating the payment session for the HPP Lightbox, the hppType must be set to lightbox. In addition, the originUrl becomes a required field. This field determines the host that will display the HPP Lightbox. The originUrl field is also copied to the frame-ancestor directive. For more information, see the content security policy for frame-ancestors.

The originUrl field only supports full URLs with http or https as the protocol. The full regex expression allowed for this field is https?://[^/]{2,}.*

Furthermore, the originUrl field only supports host-source formats. For the payment session you are creating, the URL may include a leading wildcard (*). Note that single quotes (') are not allowed.

The following are acceptable originUrl examples that follow the host-source formats:

  • http://*.mysite.com - This will match if accessing from any subdomain of mysite.com using the http protocol.
  • https://store.mysite.com - This will match if accessing store.mysite.com using the https protocol.
  • https://store.mysite.com:443 - Port numbers are supported. You may even use wildcards to indicate that all legal ports are valid. However, most servers use well-known port numbers so most http/https URLs omit them.

The following is an invalid originUrl example:

  • https://store.mysite.com/accessories - Although this follows the host-source format, it does not meet the regex expression defined by Converge. The regex expression allowed for the originUrl does not allow the use of specific web pages as the host.

For more information on creating payment sessions, see the Payment Sessions resource. 

HTML Approach

One way to launch the Lightbox is to create a button that calls the Lightbox script provided by Converge. This script can be requested by using an HTML form similar to the following:

<form method="POST" action="/%3Cyour-hosted-card-accepting-endpoint%3E">
    <script
        src="https://<hpp-url>/client/index.js"
        class="converge-button"
        data-session-id="<your-payment-session-id>"
    ></script>
</form>

By default, HTML is static. In order to apply the dynamically generated Session ID to the previous example, you will need to generate this value. Fortunately, there are plenty of ways to generate this form. Most web development frameworks such as Express, Django, ASP.net, and Rails support server-side templating. Most front-end-frameworks such as Angular, React, and Vue include robust options for dynamic HTML. If you are working without the benefit of these tools, you can still achieve comparable results using vanilla javascript by defining a function similar to the following:

const sessionId = ... // Define a process to retrieve the Session ID for the payment session from your server.

function generateLightboxButton(sessionId) {
    const target = document.querySelector("#lightbox-form"); // Target the form you want to place the script inside of.
    const buttonScript = document.createElement("script"); // Create a script element using the DOM API.
    buttonScript.setAttribute("src", "https://<hpp-url>/client/index.js"); // Set to the HPP URL you are using.
    buttonScript.setAttribute("class", "converge-button"); // Use whichever class you would like to provide styling.
    buttonScript.setAttribute("data-session-id", `${sessionId}`); // Pass the sessionId as a string.
    target.appendChild(buttonScript);
}
generateLightboxButton(sessionId)

Client Library Approach

You can include the Client Library on your page. Follow the process below to begin:

  • Start by adding <script src="https://<hpp-url>/client/library.js"></script> to your code.
  • Create the Lightbox by passing a sessionId and messageHandler to the constructor.
  • Open the instance with lightbox.show() when you are ready. The library will bind itself to window.ConvergeLightbox when loaded. This is a constructor function that returns a Lightbox instance with show() and hide() methods.
  • The window.ConvergeLightbox constructor takes a single argument that is an object with the sessionId, messageHandler, and optional onReady keys.
  • The sessionId is the payment session that was created by a server-to-server call. The Lightbox user cannot modify this session.
  • The messageHandler is a function that takes two arguments: the message itself and a function that will run the built-in default action for a given message type.
  • The message object will have a type field to define what kind of message it is and other data fields depending on the message type. The example code below displays message data for different message types.
  • All valid message types are defined in the window.ConvergeLightbox.MessageTypes map. Do not use string values.
  • If doCreateTransaction in the payment session is true, the MessageTypes.hostedCardCreated message will never be sent. If doCreateTransaction is false, the MessageTypes.transactionCreated event will never fire.
  • If an error occurs in the Lightbox that cannot be recovered without the creation of a new payment-session, the MessageTypes.error event will fire with a JavaScript Error object in the messages error field.
  • The onReady function uses a single boolean argument to reflect if the Lightbox encountered an error when loading. The argument will be true if there was an error and false if the Lightbox loaded successfully. You can use this callback after the Lightbox initialization is complete.
const MessageTypes = window.ConvergeLightbox.MessageTypes;

const submitData = (data) => {
  // send data to your server
  console.log(data);
};

let lightbox;

function onClickHandler() {
  // do work to create a sessionId
  const sessionId = 'your-new-session-id';
  if (!lightbox) {
    lightbox = new window.ConvergeLightbox({
      sessionId: sessionId,
      onReady: (error) =>
        error
          ? console.error('Lightbox failed to load')
          : lightbox.show(),
      messageHandler: (message, defaultAction) => {
        switch (message.type) {
          case MessageTypes.transactionCreated:
            submitData({
              sessionId: message.sessionId,
            });
            break;
          case MessageTypes.hostedCardCreated:
            submitData({
              convergePaymentToken: message.hostedCard,
              hostedCard: message.hostedCard,
              sessionId: message.sessionId,
            });
            break;
        }
        defaultAction();
      },
    });
  } else {
    lightbox.show();
  }
}