Service Architecture
Overview
The wallet-payment-service is a backend microservice responsible for orchestrating the complete payment lifecycle in the Convenient Checkout platform. It sits behind the API gateway and coordinates between merchants, the checkout widget, the Stripe payment processor, and downstream notification systems.
High-Level Component Diagram
The Stripe Adapter (wallet-stripe-adapter-service) is a separate microservice that communicates with wallet-payment-service asynchronously via Azure Event Grid, not via direct HTTP calls. This decouples payment orchestration from vendor integration.
The Merchant Service (wallet-merchant-service) is responsible for receiving terminal state events and orchestrating webhook delivery to merchants. It delegates the actual HTTP delivery to the Merchant Webhook Proxy (wallet-merchant-webhook-proxy), which handles payload signing, retry logic, and at-least-once delivery guarantees.
Layer Responsibilities
Controller Layer
| Responsibility | Details |
|---|---|
| Request deserialization | Parse and bind incoming JSON to request DTOs |
| Header extraction | Read X-Merchant-Id, X-Upstream-Env, X-Source |
| Input validation | Bean validation (@Valid), schema-level constraints |
| Response mapping | Map service results to HTTP response codes (200, 202, 4xx, 5xx) |
| No business logic | Controllers must not contain payment rules or state transitions |
Service Layer
| Responsibility | Details |
|---|---|
| Payment orchestration | State machine transitions, flow routing (single vs split-tender) |
| Idempotency enforcement | Dedup check on merchantTransactionId |
| Customer resolution | Lookup/create customer via identifier priority chain |
| Allocation processing | Iterate allocations, delegate to adapter, handle rollback |
| Event emission | Trigger webhook events on terminal state transitions |
Stripe Adapter (wallet-stripe-adapter-service)
This is a separate microservice, not a layer within wallet-payment-service. It communicates via Azure Event Grid.
| Responsibility | Details |
|---|---|
| Vendor abstraction | Translate internal payment events to Stripe PaymentIntent API calls |
| Error translation | Map Stripe error codes to internal error taxonomy and publish result events |
| Resilience | Circuit breaker, timeout, retry policies for Stripe calls |
| Idempotency keys | Pass merchantTransactionId as Stripe idempotency key |
| Event consumption | Subscribe to payment events from Event Grid, publish result events back |
Merchant Service & Webhook Proxy (wallet-merchant-service → wallet-merchant-webhook-proxy)
The Merchant Service (wallet-merchant-service) is the domain owner for merchant configuration, onboarding, and webhook event delivery. It subscribes to terminal state events via Event Grid, builds the webhook payload, and delegates delivery to the Merchant Webhook Proxy (wallet-merchant-webhook-proxy).
The Webhook Proxy handles the actual HTTP delivery to the merchant's registered endpoint. This separation keeps the merchant service focused on domain logic while the proxy handles transport-level concerns.
Merchant Service responsibilities:
| Responsibility | Details |
|---|---|
| Event consumption | Subscribe to terminal events (COMPLETED, FAILED, CANCELLED, etc.) from Event Grid |
| Merchant configuration | Manage merchant settings, onboarding, and webhook URL registration |
| Payload construction | Build webhook payload from event data using merchant-specific settings |
| Delivery delegation | Forward constructed payloads to the Webhook Proxy for delivery |
Webhook Proxy responsibilities:
| Responsibility | Details |
|---|---|
| HTTP delivery | POST to merchant-registered webhook URL |
| Retry | At-least-once delivery with exponential backoff |
| Security | Sign payloads with HMAC, include verification headers |
Repository Layer
| Responsibility | Details |
|---|---|
| Data persistence | CRUD operations on payment, allocation, customer tables |
| Transaction boundaries | Ensure atomicity of state transitions |
| Query patterns | Lookup by paymentId, merchantTransactionId, merchantId |
| Audit columns | Maintain createdAt, updatedAt, createdBy |
Security Boundaries
| Boundary | Mechanism |
|---|---|
| Merchant → API Gateway | OAuth 2.0 bearer token. Scopes: merchant, user, merchant-pci |
| Payment Service ↔ Event Grid | Azure-managed authentication; service identity |
| Stripe Adapter → Stripe | API key authentication (secret key stored in vault) |
| Service → Database | Connection pooling with encrypted credentials |
| Merchant Service → Webhook Proxy → Merchant | Signed payload with HMAC, OAuth2/JWT verification |
Sensitive customer and card data (PAN, CVV, full SSN) must never be logged, stored in plaintext, or exposed in API responses. All card data is tokenized by Stripe — services only store masked references (last four, brand, expiry). See Security & Compliance.