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 the following pieces of information:

  • Session ID: This is obtained from creating a payment session. See Server-Side Scripting for more information.

  • Public API Key: This is one of the pieces of information given to you when onboarding.

  • Merchant Alias: This is another piece of information given to you when onboarding.

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 Session ID from a payment session request and will need to add that information into the template URL before it will work correctly.

One way to launch the lightbox is to create a button which calls the lightbox script provided by Converge. This script can be invoked by 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 dynamically generate this value.  Fortunately, there are plenty of ways to generate this form dynamically. Most web development frameworks such as Express, Django,, and Rails support server-side templating and 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 similar 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.

Example: A Javascript Approach

The following code is one example of how to approach this.

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.transactionAuthorized:
          case MessageTypes.transactionDeclined:
              transactionId: message.transactionId,
              sessionId: message.sessionId,
          case MessageTypes.hostedCardCreated:
              convergePaymentToken: message.hostedCard,
              hostedCard: message.hostedCard,
              sessionId: message.sessionId,
  } else {;