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:
  • Production:

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.

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">

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,, 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.

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 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 argument (a boolean) 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

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) =>
          ? console.error('Lightbox failed to load')
      messageHandler: (message, defaultAction) => {
        switch (message.type) {
          case MessageTypes.transactionCreated:
              sessionId: message.sessionId,
          case MessageTypes.hostedCardCreated:
              convergePaymentToken: message.hostedCard,
              hostedCard: message.hostedCard,
              sessionId: message.sessionId,
  } else {;