Widget Capabilities

This page consolidates all major widget capabilities and the overall widget experience for the Convenient Checkout UI. It includes lifecycle, guest vs wallet, container types, and all supported modes. Use this as your single reference for widget integration, configuration, and troubleshooting.

---

Widget Experience Overview

The Convenient Checkout Widget provides a unified payment and wallet experience for merchants and customers. It supports multiple integration patterns (hosted, embedded, modal, inline, drawer) and adapts to both guest and wallet users automatically.

---

Session Lifecycle

The widget experience is driven by a session created via the Sessions API. Poll the session endpoint to track status and update your UI accordingly.

Status	Description
ACCEPTED	Session initiated, not ready for processing
CREATED	Ready for processing (e.g., payment, add method)
COMPLETED	Transaction successful (payment, method added, etc.)
error	Invalid request, creation error, transaction failure, or timeout

---

Guest vs Wallet Experience

The widget automatically determines whether to show a wallet or guest experience based on the session’s customer object:

• Wallet experience: Displayed if customer.enterpriseId, customer.hsid, or a valid merchant identifier is present.
• Guest experience: Displayed otherwise.

Sample session object:

{
  "payment": { ... },
  "customer": {
    "email": "<email>",
    "enterpriseId": "<enterpriseId>",
    "hsid": "<hsid>",
    "metaData": { "userId": "<userId>" }
  }
}

---

Widget Containers & Modes

The widget supports multiple container types and combinations for flexible UI integration:

Primary Only Containers

• Types: inline, modal, drawer

Primary and Secondary Containers

• Primary: inline
• Secondary: modal, drawer

Capabilities by Container Type

	Inline	Modal	Drawer
Payment with wallet	✅	✅	✅
Payment	✅	✅	✅
Wallet management	✅	✅	✅
Add payment method	✅	✅	✅
Payment method selector	✅	❌	❌
Payment method display	✅	❌	❌

---

---

Add Payment Method (PAYMENT_METHOD_ENTRY)

Purpose: Enable customers to save payment methods (card or bank account) via a secure UI. Agents can also send entry links to customers.

When to use: When you want users to add a new card or bank account to their wallet for future payments.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "customer": { "enterpriseId": "...", "hsid": "...", ... },
  "config": { "modes": ["PAYMENT_METHOD_ENTRY"] }
}

---

One-Time Payment (PAYMENT)

Purpose: Allow customers to make a payment using card, bank account, or digital wallet (Google Pay, Apple Pay).

When to use: For single payments, optionally with card saving.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "payment": { "amount": 1500, "description": "...", ... },
  "customer": { "enterpriseId": "...", "hsid": "...", ... }
}

---

Payment With Wallet (PAYMENT_WITH_WALLET)

Purpose: Let customers pay using any saved method in their wallet (card, bank, Google Pay, Apple Pay).

When to use: For returning users with stored payment methods.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "payment": { "amount": 1500, "description": "...", ... },
  "customer": { "enterpriseId": "...", "hsid": "...", ... },
  "config": { "modes": ["PAYMENT_WITH_WALLET"] }
}

---

Manage Wallet (WALLET)

Purpose: Allow customers (or agents) to add, edit, or remove payment methods in their wallet.

When to use: For full wallet management scenarios.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "customer": { "enterpriseId": "...", "hsid": "...", ... },
  "config": { "modes": ["WALLET"] }
}

---

Payment Method Selector (PAYMENT_METHOD_SELECT)

Purpose: Show all saved payment methods for selection, notify on selection, and optionally pre-select a method.

When to use: When you want users to choose from multiple saved payment methods.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "customer": { "enterpriseId": "...", "hsid": "...", ... },
  "paymentMethod": { "id": "payment-method-id" },
  "config": { "modes": ["PAYMENT_METHOD_SELECT"] }
}

---

Payment Method Display (PAYMENT_METHOD_DISPLAY)

Purpose: Present a specific payment method in a card-like UI during checkout or to highlight a preferred option.

When to use: To display a single payment method for review or selection.

Prerequisites:

• Merchant account on CCG Platform
• Valid merchantId for API requests

Supported Experiences: Hosted, Embedded

Example Session Request:

{
  "customer": { "enterpriseId": "...", "hsid": "...", ... },
  "paymentMethod": { "id": "payment-method-id" },
  "config": { "modes": ["PAYMENT_METHOD_DISPLAY"] }
}

---

Related Documentation

• Sessions API — Session creation, mode configuration, and full request payloads
• Integration Overview

The following matrix summarizes which UI modes and types are supported for each widget capability:

Mode / Type	Hosted	Embedded: Inline	Embedded: Modal	Embedded: Drawer	Embedded: Inline-Modal	Embedded: Inline-Drawer
PAYMENT	✅	✅	✅	✅	❌	❌
PAYMENT_METHOD_ENTRY	✅	✅	✅	✅	❌	❌
PAYMENT_WITH_WALLET	✅	✅	✅	✅	✅	✅
WALLET	✅	✅	✅	✅	✅	✅
PAYMENT_METHOD_SELECT	✅	✅	❌	❌	✅	✅

---

Explanation

The Convenient Checkout Widget is a modular UI component that supports a variety of payment and wallet management scenarios for merchants and customers. Each capability (mode) is designed for a specific use case, such as adding a payment method, making a payment, managing a wallet, or selecting/displaying payment methods. The widget supports both self-service and agent-assisted flows, and can be integrated in hosted, embedded, modal, inline, or drawer experiences. Configuration options allow merchants to tailor the widget to their business needs, including which payment channels and methods are available, and how user consent and PCI compliance are handled.

---

Frequently Asked Questions (FAQ)

General

Q: What is the Convenient Checkout Widget? A: It is a flexible, embeddable UI component that enables merchants to offer payment, wallet, and account management features to their customers, supporting multiple payment methods and integration patterns.

Q: What are the main widget modes/capabilities? A: The main modes are PAYMENT, PAYMENT_METHOD_ENTRY, PAYMENT_WITH_WALLET, WALLET, PAYMENT_METHOD_SELECT, and PAYMENT_METHOD_DISPLAY. Each mode is tailored for a specific scenario (see above sections).

Q: What are the prerequisites for using the widget? A: Merchants must have a CCG Platform account, complete onboarding, and obtain a valid merchantId . Payment channels must be enabled during onboarding.

Q: What integration patterns are supported? A: Hosted, embedded (inline, modal, drawer), and combinations such as inline with modal or drawer, depending on the mode.

Q: What happens if an invalid customer identifier or payment method ID is provided? A: Session creation will fail with an error, or the widget will display a message such as "Payment Method Not Available."

---

By Mode

PAYMENT_METHOD_ENTRY

• Enables customers to save payment methods (card/bank). Agents can assist via SMS, email, webform, or telephonic entry.
• If a channel is not enabled during onboarding, it will not be available.

PAYMENT

• Allows customers to make payments using card, bank, Google Pay, or Apple Pay. Agents can assist via multiple channels.
• Payment methods can be saved for future use if the user opts in and the transaction is successful.

PAYMENT_WITH_WALLET

• Lets customers pay with any saved method. If no methods are saved, the widget prompts to add one.
• Adding a duplicate card/bank updates the existing entry.

WALLET

• Allows customers to add, edit, or remove payment methods. If no methods exist, prompts to add one.

PAYMENT_METHOD_SELECT

• Lets users select from saved payment methods. Merchants are notified of selection via callback (embedded) or polling (hosted).
• Invalid payment method IDs are ignored; no pre-selection occurs.

PAYMENT_METHOD_DISPLAY

• Displays a specific payment method. If the ID is missing or invalid, shows "Payment Method Not Available."

---

For more details, see the configuration and usage examples in each section above, or refer to the Widget API Reference.