Skip to main content
Version: v2

Hosted Experience

Our Embedded Experience allows you to integrate the payment widget directly into your existing website with just a few lines of code. It maintains a seamless brand journey for your customers while we handle the heavy lifting of PCI compliance, session security, and automated translations.

When to Use​

  • You want the fastest integration with minimal code changes
  • You prefer a pop-up experience separate from your main app
  • You do not need deep UI customization or in-app embedding

Key Benefits​

  • No need to embed or style the widget in your app
  • Supports all major widget capabilities and payment methods
  • Easy to implement and maintain

Setup Overview​

  1. Complete onboarding and obtain your merchantId (see Getting Started)
  2. Create a session from your backend — see Sessions API for full request/response details
  3. Use the hostedUrl from the session response to open the widget in a popup
  4. Poll the session status to detect completion or listen for widget callbacks
  5. Close the popup on completion or error

Example: Launching the Widget​

const openCCGWidget = function(hostedUrl) {
  var width = 400;
  var height = 850;
  var left = window.screen.width / 2 - width / 2;
  var features = "popup=true,width=" + width + ",height=" + height + ",left=" + left;
  var widgetPopupInstance = window.open(hostedUrl, "_blank", features);
  // Poll for session status and close on completion
};

Full Integration Example​

var widgetPopupInstance = null;
var popupWindowCancelPollingInterval = null;
var POPUP_WINDOW_CLOSED_CHECK_INTERVAL = 500;

function onError(err) {
  console.error("Session errored", err);
  closeCCGWidget();
}

function onClosePopup() {
  console.log("popup window was closed.");
}

function openCCGWidget(hostedUrl) {
  var width = 400;
  var height = 850;
  var left = window.screen.width / 2 - width / 2;
  var features = "popup=true,width=" + width + ",height=" + height + ",left=" + left;

  if (!widgetPopupInstance || widgetPopupInstance.closed) {
    widgetPopupInstance = window.open(hostedUrl, "_blank", features);
  } else {
    widgetPopupInstance.location = hostedUrl;
    widgetPopupInstance.focus();
  }

  popupWindowCancelPollingInterval = window.setInterval(function() {
    if (widgetPopupInstance && widgetPopupInstance.closed !== false) {
      onClosePopup();
      clearInterval(popupWindowCancelPollingInterval);
    }
  }, POPUP_WINDOW_CLOSED_CHECK_INTERVAL);
}

function closeCCGWidget() {
  if (widgetPopupInstance) widgetPopupInstance.close();
}

function setupEventListeners() {
  var checkoutBtn = document.querySelector("#checkoutBtn");
  checkoutBtn.addEventListener("click", async function(event) {
    event.preventDefault();
    closeCCGWidget();

    var session = await generateSessionFromBackend();
    var hostedUrl = session && session.data && session.data.hostedUrl;

    if (hostedUrl) {
      openCCGWidget(hostedUrl);
      pollSessionStatus({ url: session.url, onCompleted: onCompleted, onError: onError });
    } else {
      onError(session);
    }
  });
}

setupEventListeners();

Troubleshooting & FAQ​

Q: How do I know when the session is complete? A: Poll the url returned in the session response and close the popup when status is COMPLETED. See Sessions API — Status Handling.

Q: Can I customize the widget UI? A: Hosted Experience offers limited customization. For full control, use Embedded Experience.

Q: What if the popup is blocked? A: Ensure the popup is triggered by a user action (e.g., button click) to avoid browser popup blockers.