Skip to main content
Version: v1

Getting Started

Get the CCG widget running in your application in minutes. This guide covers prerequisites, installation, and a minimal working integration.

What you'll need
  • A CCG merchant account and merchantId
  • A session token from the Sessions API
  • A container element in your page for the widget to render into

Step 1: Create a Session​

Before launching the widget, your backend must create a session via the Sessions API. The session token controls what the widget displays and what the user can do.

POST /sessions

See the Sessions API for full request/response details, including mode configuration and digital wallet setup.

Step 2: Install the Widget​

Choose the installation method that best fits your project:

Option A — CDN (Script Tag)​

Paste this script tag into your HTML page. No build step required.

<!-- Add a container where the widget will render -->
<div id="ccg-widget-container"></div>

<!-- Load the CCG widget -->
<script src="https://cdn.healthsafepay.com/wallet/ccg-widget.min.js"></script>

Option B — NPM (Recommended for React / TypeScript projects)​

npm install @optum-ccg/convenient-checkout-ui

Step 3: Initialize the Widget​

Once the script is loaded and you have a session token, initialize the widget:

CDN​

const options = {
  rootElement: document.querySelector("#ccg-widget-container"),
  checkoutSessionId: "REPLACE_WITH_CHECKOUT_SESSION_ID",
  appEnv: "prod",
  onSuccess: function(data) {
    console.log("Payment complete", data);
  },
  onError: function(data) {
    console.error("Payment error", data);
  },
  onEvent: function(data) {
    console.log("Widget event", data);
  }
};

const widget = window.OptumCCGWidgetInitializer(options);
widget.render();

NPM / TypeScript​

import { OptumCCGWidgetInitializer, OptumCCGWidgetOptions } from "@optum-ccg/convenient-checkout-ui/dist/widget/ccg-widget.min";

const options: OptumCCGWidgetOptions = {
  rootElement: document.querySelector("#ccg-widget-container") as HTMLElement,
  checkoutSessionId: "REPLACE_WITH_CHECKOUT_SESSION_ID",
  appEnv: "prod",
  onSuccess: (data) => console.log("Payment complete", data),
  onError: (data) => console.error("Payment error", data),
  onEvent: (data) => console.log("Widget event", data),
};

const widget = OptumCCGWidgetInitializer(options);
widget.render();

For full type definitions and a React example, see TypeScript Support.

Integration Models at a Glance​

ModelHow it RendersWhen to Use
Embedded — InlineRendered inline inside your pageFull in-page checkout experience
Embedded — ModalRendered as a modal overlayPop-up without leaving your page
Embedded — DrawerRendered as a slide-in drawerSidebar-style checkout
HostedBrowser pop-up managed by CCGMinimal frontend code required

For detailed setup per model, see the Integration Overview.

Next Steps​

What to doWhere to go
Choose Hosted or EmbeddedIntegration Options
Set up TypeScript typesTypeScript Support
Understand widget modes & capabilitiesWidget Capabilities
Customize appearanceTheming & Styling
Set up language / translationLocalization & Translation
Go to full API referenceAPI Reference

Authentication & Security​

The widget is driven entirely by the backend-issued session token. No direct user credentials are passed through the widget. Token expiry and session lifecycle are handled by the Sessions API. For PCI-related events during widget use, see PCI Engagement Notification.

Versioning & Backward Compatibility​

See Versioning for supported package versions, breaking changes, and deprecation timelines.