V2 Implementations — Engineering Guide
🔒 InternalInternal information — not visible in the public (merchant) site.
Purpose
This engineering guide is the single source of truth for any software engineer building, maintaining, or extending v2 implementations across the Convenient Checkout platform. It is not limited to a single service or endpoint — it spans every domain, every service, and the shared commons library that ties them together.
Whether you are implementing a new payment flow, adding a customer lookup strategy, onboarding a new merchant, or building a reporting pipeline, this guide provides the standards, patterns, architecture decisions, and best practices you must follow.
Who This Guide Is For
| Role | Start Here |
|---|---|
| Backend engineer — new to V2 | V1 vs V2 — What Changed and Why → Shared Standards → Commons Library → relevant domain section |
| Backend engineer — working on payments | Payment Lifecycle States → Split-Tender Payment |
| Backend engineer — working on commons library | Commons Library — Versioning & Deployment Strategy |
| QE / test engineer | Testing Strategy + API Design Conventions + relevant domain section |
| Reviewing a PR | Coding Standards + Error Strategy + relevant domain section |
| Investigating a production issue | Troubleshooting → Observability |
Platform Ecosystem
The Convenient Checkout platform is a microservices architecture consisting of the following services, all sharing wallet-event-commons:
| Service | Domain | Description |
|---|---|---|
wallet-payment-service | Payments | Payment lifecycle: create, authorize, capture, cancel |
wallet-customer-service | Customers | Customer identity, wallet, payment method management |
wallet-merchant-service | Merchants | Merchant configuration, onboarding, settings, and webhook event delivery to merchants (via wallet-merchant-webhook-proxy) |
wallet-auth-service | Sessions | Session creation, checkout session management |
wallet-stripe-adapter-service | Vendor | Stripe API abstraction layer |
wallet-reporting-service | Reporting | Transaction reporting and reconciliation |
wallet-notification-service | Notifications | Email, SMS, and webhook dispatch |
wallet-migration-service | Migration | v1 → v2 data migration |
wallet-api-internal | Internal | Internal operations and admin tools |
wallet-achavs-service | ACH | ACH account verification |
wallet-eimp-data-sync-service | Data Sync | Enterprise identity data synchronization |
wallet-telephonic-api-adapter-service | Telephonic | Phone-based payment entry |
wallet-event-commons | Shared | Common library: DTOs, enums, events, rules, validators |
Shared Standards
These apply to all domains and all services. Every v2 implementation must comply:
| Standard | What It Governs | Key Rule |
|---|---|---|
| V1 vs V2 Guide | What changed, migration checklist, side-by-side comparisons | Read this first if coming from V1 |
| API Design Conventions | URL patterns, HTTP methods, status codes, request/response envelopes | Resources as plural nouns, 202 for async, amounts in cents |
| Coding Standards | Package structure, Lombok, Reactor, constants, exceptions, Javadoc | No magic strings, no .block(), no swallowed exceptions |
| Security & Compliance | Data protection, OAuth2 scopes, data masking, audit trails | Never log sensitive data; all state transitions audited |
| Commons Library | Shared DTOs, enums, events, versioning & deployment strategy | All cross-service contracts live in wallet-event-commons; V1 and V2 packages coexist during migration |
| Error Handling | Error taxonomy, Problem DTO, error propagation | Use ErrorGroup enum; 400/422/500 classification |
| Idempotency | Dedup, retry semantics | Domain-specific idempotency keys (5 attempts max) |
| V2 Endpoint Environment Controls | Operation readiness, routing, and @V2NotImplemented stubs | V2 is available in production; confirm each operation and merchant enablement; stubs return 501 where routed |
| Architecture Patterns | Layered architecture, async boundaries | Controller → Service → Adapter → Repository |
| Testing | Test pyramid, coverage, naming | Unit + Integration + Contract tests on every PR |
| Observability | Logging, monitoring, alerting, dashboards | Azure Application Insights + Splunk; structured JSON logs |
Domain Guides
Each domain has its own section covering domain-specific flows, data models, API contracts, and webhook events:
| Domain | Service | Status |
|---|---|---|
| Payments | wallet-payment-service | ✅ Authored |
| Customers | wallet-customer-service | 🔲 Planned |
| Merchants | wallet-merchant-service | 🔲 Planned |
| Reporting | wallet-reporting-service | 🔲 Planned |
| Sessions | wallet-auth-service | 🔲 Planned |
| Disputes | wallet-payment-service | 🔲 Planned |
| Notifications | wallet-notification-service | 🔲 Planned |
V2 API Inventory
| Method | Path | Domain | Operation |
|---|---|---|---|
POST | /v2/payments | Payments | Create payment (single or split-tender) |
GET | /v2/payments?merchantTransactionId={id} | Payments | Get payment by merchant ID |
GET | /v2/payments/{paymentId} | Payments | Get payment by platform ID |
PATCH | /v2/payments/{paymentId}/cancel | Payments | Cancel a payment |
PATCH | /v2/payments/{paymentId}/capture | Payments | Capture a pre-authorized payment |
POST | /v2/token/payments | Payments (Token) | Create payment with raw card token |
POST | /v2/refunds | Payments | Create a refund |
GET | /v2/refunds/{refund-id} | Payments | Get refund status |
POST | /v2/sessions | Sessions | Create checkout session |
GET | /v2/sessions/{sessionId} | Sessions | Get session details |
GET | /v2/checkout-sessions/{checkoutSessionId} | Checkout Sessions | Get checkout session status |
PATCH | /v2/checkout-sessions/{checkoutSessionId} | Checkout Sessions | Update checkout session (operation-based) |
PATCH | /v2/checkout-sessions/{checkoutSessionId}/cancel | Checkout Sessions | Cancel checkout session |
POST | /v2/checkout-sessions/{checkoutSessionId}/child-sessions | Checkout Sessions | Create child session |
Current State vs. Target State
This guide also serves as a living improvement roadmap. Each section documents:
- Current State — How things work today, including known limitations
- Target State — What a world-class implementation in a regulated payments platform should look like
- Migration Path — Concrete steps to get from current to target
| Area | Current State | Target State | Priority |
|---|---|---|---|
| Commons v1/v2 coexistence | v1 DTOs (event/) and v2 DTOs (events/v2/) both active | All services consume v2 models only; v1 deprecated | P1 |
| Enum duplication | Some enums exist in both enums/ and event/shared/ packages | Single canonical location in enums/ | P1 |
| Error model | ErrorResponse (v1) and Problem (v2) coexist | All v2 services use Problem; v1 ErrorResponse deprecated | P2 |
| Domain separation | Services have mixed domain concerns | Clear bounded contexts per service | P2 |
| Test coverage | Varies by service, no enforced minimum | ≥80% unit, ≥60% integration across all services | P2 |
| Observability | Basic logging, partial tracing | Structured logging + distributed tracing + domain dashboards | P3 |
| API documentation | OpenAPI spec maintained manually | Schema-first development; generated validation from spec | P3 |
| Contract testing | Not consistently applied | Consumer-driven contracts between all services | P3 |
See the Improvement Roadmap for the full migration plan.
How This Guide Is Organized
10-v2-implementations/
├── 1-overview.md ← You are here
├── 2-architecture/ ← Service design, domain model, request lifecycle
├── 3-commons-library/ ← wallet-event-commons: DTOs, enums, events, rules
├── 4-shared-standards/ ← Cross-domain: API design, security, errors, idempotency
├── 5-domains/
│ ├── payments/ ← Payment flows, webhooks, error codes
│ ├── customers/ ← (planned) Customer resolution, wallet management
│ ├── merchants/ ← (planned) Merchant config, onboarding
│ └── reporting/ ← (planned) Transaction reports
├── 6-testing/ ← Strategy, unit/integration/contract, test data
├── 7-troubleshooting/ ← Error patterns, debugging workflow
└── 8-improvement-roadmap/ ← Current → target state, migration phases
Also see (engineering-guide-level, not v2-exclusive):
└── observability/ ← Logging, App Insights, Splunk, dashboards, alerting
Related Documentation
| Resource | Link |
|---|---|
| Payment API Reference (OpenAPI) | API Reference V2 |
| Webhook Reference | Webhooks V2 |
| Payment Error Codes | Error Codes |
| Business Guide — Payments | Business Payments |
| Test Scenarios & Data | Test Cards |