CCG Microservices Overview
Document Status — Draft
Status: Draft — April 21, 2026 | Audience: Engineers and TPMs
Reviewer: ranga_chenna@optum.com
⚠️ This document is a work in progress and must be kept up to date as services evolve. Engineers making changes to service contracts, flows, or configurations are expected to reflect those changes here before merging.
Several services are marked "yet to be documented."
1. System Overview
The Convenient Checkout Gateway (CCG) is a payment gateway that enables merchants to integrate a hosted checkout UI or API-first payment flows into their platforms. It supports one-time payments, saved payment methods (pay-and-save), split-tender transactions, refunds, and reporting.
Architectural Style
CCG uses a hybrid architecture combining three integration patterns:
| Pattern | Used For |
|---|---|
| Synchronous REST | Real-time payment, session, and customer operations |
| Event-driven | Merchant configuration propagation and outbound webhook notifications |
| File-based ingestion | customer and Payment method migration from other payment gateways |
Key Integration Patterns
- Merchants integrate via a widget (UI) initialized through
wallet-auth-service, or directly via the API. - Payment orchestration is owned by
wallet-payment-service, which delegates processor-level operations towallet-stripe-adapter-service. - Merchant configuration changes and payment events are propagated outbound as webhooks via
wallet-merchant-service.
2. Service Catalog
warning
⚠️ This is the source of truth for service responsibilities. Update this when adding or modifying services.
CCG is composed of seven documented microservices. Each service owns a distinct domain and communicates with others through well-defined interfaces.
note
Additional services exist but are not yet documented.
Services at a Glance
| Service | Primary Role |
|---|---|
wallet-auth-service | Session and authorization entry point for UI integrations |
wallet-merchant-service | Merchant configuration and webhook dispatch |
wallet-customer-service | Customer identity, wallets, and payment method lifecycle |
wallet-payment-service | Payment orchestration and transaction state management |
wallet-stripe-adapter-service | Stripe integration and model translation layer |
wallet-reporting-service | Merchant reporting and payout views |
wallet-migration-service | Bulk migration of card/ACH payment instruments |
Service Details (Collapsible)
wallet-auth-service - Session and authorization entry point
| Attribute | Details |
|---|---|
| Purpose | Entry point for merchant UI integration; manages sessions and authorization |
| Key Responsibilities | Session creation/retrieval, widget initialization, scope-level authorization |
| Upstream callers | Merchants (widget consumers), external API clients |
| Downstream dependencies | wallet-merchant-service (merchant config validation); possibly wallet-customer-service (session context resolution) - not confirmed |
| Data Ownership | Sessions, scopes/permissions |
wallet-merchant-service - Merchant config and webhook notifications
| Attribute | Details |
|---|---|
| Purpose | Owns all merchant configuration and settings; drives outbound notifications |
| Key Responsibilities | Merchant config storage, publishing config/settings change events, dispatching webhooks for payments and payment-method events |
| Upstream callers | Internal services consuming merchant config, admin tooling |
| Downstream dependencies | Not documented |
| Data Ownership | Merchant profiles, webhook subscriptions, merchant settings |
wallet-customer-service - Customer identity and wallet lifecycle
| Attribute | Details |
|---|---|
| Purpose | Owns customer identity and the payment method/wallet lifecycle |
| Key Responsibilities | Customer identification, wallet resolution, payment method search/retrieval/update/deletion, set-up payment method flows |
| Upstream callers | wallet-payment-service, merchant API clients |
| Downstream dependencies | wallet-stripe-adapter-service (Stripe-side customer/wallet sync) - not confirmed |
| Data Ownership | Customer records, wallets, payment methods |
wallet-payment-service - Payment orchestration engine
| Attribute | Details |
|---|---|
| Purpose | Orchestrates all payment transactions |
| Key Responsibilities | Payment initiation, capture, refund submission, split-tender support, one-time pay, pay-and-save, token-based payment flows |
| Upstream callers | Merchants (API), wallet-auth-service (session-gated flows), internal clients |
| Downstream dependencies | wallet-stripe-adapter-service, wallet-customer-service |
| Data Ownership | Payment records, refund records, transaction state |
wallet-stripe-adapter-service - Stripe integration adapter
| Attribute | Details |
|---|---|
| Purpose | Adapter / anti-corruption layer between CCG and Stripe |
| Key Responsibilities | Submits payments to Stripe, manages Stripe-side wallets and customers, translates CCG payment models to Stripe API contracts |
| Upstream callers | wallet-payment-service; possibly wallet-customer-service |
| Downstream dependencies | Stripe (external payment processor) |
| Data Ownership | Stripe-mirrored state only - source of truth is upstream CCG services |
wallet-reporting-service - Financial reporting surface
| Attribute | Details |
|---|---|
| Purpose | Provides financial reporting for merchants |
| Key Responsibilities | Payout reports, combined payout reports |
| Upstream callers | Merchant API clients, internal tooling |
| Downstream dependencies | Not documented |
| Data Ownership | Report data, payout aggregations |
wallet-migration-service - Bulk payment instrument migration
| Attribute | Details |
|---|---|
| Purpose | Handles bulk migration of existing payment instruments |
| Key Responsibilities | Ingests Card and ACH migration files (via ECG) from merchants |
| Upstream callers | Merchant-initiated (file-based via ECG) |
| Downstream dependencies | wallet-customer-service (to register migrated payment methods) - not confirmed |
| Data Ownership | Migration job state |
3. End-to-End Payment Flow
The sections below trace the most common flows across CCG services.
For UI-based flows, session management is a shared prerequisite and is documented once in a common flow. For Direct API flows, the same business operations are available without widget session bootstrap.
| Flow | UI (Widget) | Direct API |
|---|---|---|
| Session management | Yes | Not required |
| Pay with wallet | Yes | Yes |
| One-time pay / pay-and-save | Yes | Yes |
| Wallet/payment method management | Yes | Yes |
| Refund | No | Yes |
UI Session Management Flow
Pay with Wallet Flow
One-Time Pay and Pay-and-Save Flow
Refund Flow
Wallet Management Flow
5. APIs & Communication Patterns
This section lists the known API surface for each service and summarizes inter-service communication patterns.
Communication Patterns
| Pattern | Usage |
|---|---|
| Synchronous REST | Payment initiation, session management, customer/payment method operations — real-time request/response |
| Event publishing | wallet-merchant-service publishes internal config/settings change events and dispatches outbound webhooks to merchants |
| File-based ingestion | wallet-migration-service ingests Card/ACH migration files via ECG |
| External API call | wallet-stripe-adapter-service → Stripe REST API |
note
The internal event/messaging infrastructure (e.g., Kafka, SQS, direct HTTP) used by wallet-merchant-service is not documented.
Key APIs per service
wallet-auth-service
| Method | Path | Description |
|---|---|---|
POST | /sessions | Create session; returns token for widget initialization |
GET | /sessions | Retrieve session state |
wallet-payment-service
| Method | Path | Description |
|---|---|---|
POST | /payments | Initiate payment |
GET | /payments/{paymentId} | Retrieve by payment ID |
GET | /payments?merchantTransactionId= | Retrieve by merchant transaction ID |
PATCH | /capture-payment | Capture a pre-authorized payment |
POST | /refund | Submit refund |
GET | /refunds/{refundId} | Retrieve refund |
POST | /token/payments | Token-based payment initiation |
GET | /token/payments/{paymentId} | Retrieve token-based payment |
wallet-customer-service
| Method | Path | Description |
|---|---|---|
POST | /find-payment-method-search | Search for payment methods |
GET | /payment-methods/{paymentMethodId} | Retrieve payment method |
PATCH | /payment-methods/{paymentMethodId} | Update payment method |
DELETE | /payment-methods/{paymentMethodId} | Remove payment method |
POST | /token/set-up-payment-method | Tokenized payment method setup |
GET | /token/set-up-payment-method/{setupPaymentMethodId} | Retrieve setup status |
wallet-merchant-service
- Outbound webhooks:
paymentsevent,payment-methodevent - Internal events: Merchant config/settings change publications (mechanism not documented)
wallet-reporting-service
note
Exact endpoint paths are not yet documented.
- Payout report
- Combined payout report
wallet-stripe-adapter-service
note
Internal service only — no public API surface. Called exclusively by wallet-payment-service. Internal contract and error response schema are not documented.
6. Failure Handling & Resilience
| Concern | Detail | Status |
|---|---|---|
| Idempotency | wallet-payment-service supports idempotent payment initiation via merchantTransactionId. Retry handling is documented in Payments — Retry Handling. | Documented |
| Stripe call retry | wallet-stripe-adapter-service retries failed Stripe calls automatically with exponential backoff starting at 2 seconds, up to 3 attempts. | Documented |
| Webhook retry | Retry logic for failed outbound merchant webhook deliveries is documented in Webhook Error Handling & Retry Strategies. | Documented |
| Error propagation | wallet-stripe-adapter-service returns structured errors upstream to wallet-payment-service. The error code mapping between Stripe errors and CCG error responses is yet to be documented. | Partially documented |
| Compensation / rollback | POST /refund is the explicit compensation mechanism for completed payments. Split-tender transactions are supported via POST /payments — no partial failure handling applies. | Documented |
| Session expiry | Sessions managed by wallet-auth-service expire after 15 minutes of inactivity. Re-initialization requires a new POST /sessions call from the merchant backend. | Documented |