Integration Components
To integrate with the CCG widget, start by understanding the main user types, widget capabilities, and experience options. This guide helps you choose the right integration approach and provides links to detailed setup for each method.
All integration options require onboarding, a valid merchantId, and session setup via the Sessions API. Choose the approach that best fits your app's needs for user experience, customization, and speed of implementation.
Decision Table: Which Integration Should I Use?
| Scenario/Need | Hosted Experience | Embedded Experience | Express Checkout | TypeScript Support |
|---|---|---|---|---|
| Quickest setup, minimal code | ✅ | ❌ | ✅ | ❌ |
| Seamless in-app experience | ❌ | ✅ | ✅ | ✅ |
| Digital wallet support (Apple/Google) | ✅ | ✅ | ✅ | ✅ |
| Full UI customization | ❌ | ✅ | ❌ | ✅ |
| Type safety for widget integration | ❌ | ✅ | ❌ | ✅ |
User Types
- Wallet users: Authenticated users with a CCG wallet
- Guest users: Anonymous users (no wallet)
Widget Capabilities
Widget capabilities determine what actions a user can perform within the widget.
| Capability | Mode | User | Experience |
|---|---|---|---|
| Manage wallet and make payment | PAYMENT_WITH_WALLET | wallet | Hosted Embedded |
| Make one time payment | PAYMENT | wallet, guest | Hosted Embedded |
| Add a payment method | PAYMENT_METHOD_ENTRY | wallet | Hosted Embedded |
| Manage wallet | WALLET | wallet | Hosted Embedded |
| Payment Method Selector | PAYMENT_METHOD_SELECT | wallet | Hosted Embedded |
| Payment Method Display | PAYMENT_METHOD_DISPLAY | wallet | Embedded |
Widget Experience
Widget experience determines how the widget is presented to the user.
- Hosted: Displayed as a browser pop-up, launched separately from the parent application.
- Embedded: Integrated into the parent application (modal, inline, or drawer) for a seamless, thematically consistent experience.
- For container and capability combinations, see Widget Experience.
Integration Approaches
Choose the approach that best fits your use case:
- Hosted Experience: Fastest to implement, best for simple flows or when you want to avoid embedding code.
- Embedded Experience: Best for seamless, branded experiences inside your app.
- Express Checkout with Digital Wallets: For Apple Pay/Google Pay and frictionless checkout.
- TypeScript Support: For type-safe widget integration in modern apps.
Comparing Integration Approaches
| Embedded Experience | Hosted Experience | |
|---|---|---|
| Widget Experience (UX) | Embedded as a component into merchant app | Launched as browser pop-up |
| Session | Managed by Merchant | Managed by Merchant |
| Build Time Integration (npm) | Available | NA |
| Run Time Integration (CDN) | Available | NA |
| Usage within React App | Yes | Yes |
| Usage within Non-React App | Yes | Yes |
Onboarding & Session Setup
All integration options require:
- CCG Platform account and onboarding
- Valid
merchantId - Session creation via the Sessions API
For session request/response payloads, mode configuration, digital wallet setup, and status lifecycle, see the Sessions API.
FAQ
Q: Can I use the widget in a non-React app?
A: Yes. Both Hosted and Embedded options support React and non-React apps.
Q: How do I enable digital wallets like Apple Pay or Google Pay?
A: Use the Express Checkout integration and follow the digital wallet setup in the Sessions API guide.
Q: What is required to go live?
A: Complete onboarding, obtain a merchantId, and test session creation and widget flows in staging.
Q: Where do I find error codes and troubleshooting help?
A: See the FAQ in each integration option and the Widget Capabilities FAQ.
Integration Checklist
Use this checklist to verify readiness before going live:
- CCG Platform onboarding complete
-
merchantIdprovisioned - Widget integration approach selected (Hosted, Embedded, or Express)
- Session API integration tested
- Widget capabilities and modes validated
- Widget flows tested in staging
- Go-live readiness review complete