Skip to main content

Payment Service 💳

The Payment Service is responsible for handling payment processing and payment lifecycle management in the ShopVerse platform.

It integrates with external payment gateways (Razorpay), maintains payment state, and publishes events for downstream services such as Notification and Analytics.

🎯 Responsibilities​

The Payment Service handles:

  • Payment order creation
  • Integration with Razorpay
  • Payment status tracking
  • Handling payment callbacks/webhooks
  • Publishing payment-related events
  • Providing payment history to users

🧠 Why a Separate Payment Service?​

Payments are:

  • Security-sensitive
  • External-system dependent
  • Failure-prone

Separating them into a dedicated service ensures:

  • Clear isolation of payment logic
  • Safer handling of third-party integrations
  • Independent scaling
  • Easier compliance and auditing

🏗️ High-Level Architecture​

🔐 Security Model​

  • All APIs are accessed via API Gateway

  • Gateway injects:

    • X-User-Email
    • X-User-Role

  • Only authenticated users can initiate payments

  • Admin access is restricted to reporting APIs

  • No payment secrets exposed to clients

🔁 Payment Flow (Order → Payment)​

🗄️ Data Model​

Payment Entity​

  • id
  • orderId
  • customerId (email)
  • amount
  • razorpayOrderId
  • razorpayPaymentId
  • status (CREATED, SUCCESS, FAILED)
  • createdAt

Payment records are immutable after success.

📡 Kafka Events Published​

Event TypeTopicDescription
PAYMENT_CREATEDpayment-eventsPayment initiated
PAYMENT_SUCCESSpayment-eventsPayment completed
PAYMENT_FAILEDpayment-eventsPayment failure

Consumers:

  • Notification Service
  • Analytics Service
  • Order Service (optional status sync)

🌐 APIs​

Customer APIs​

MethodEndpointDescription
POST/api/payments/createCreate payment order
GET/api/payments/myGet user payment history

Callback API (Internal)​

MethodEndpointDescription
POST/api/payments/callbackRazorpay webhook

Webhook endpoints are not exposed publicly.

🔄 Payment Status Lifecycle​

  • CREATED → Payment order generated
  • SUCCESS → Payment confirmed via callback
  • FAILED → Payment failed or cancelled

🛡️ Reliability & Safety Measures​

  • Razorpay signature verification
  • Idempotent callback handling
  • Payment state checks before updates
  • No duplicate payment confirmations
  • Secure secret storage (env variables)

⚠️ Failure Scenarios​

❌ Razorpay API Failure​

  • Payment creation fails
  • User receives retry message

❌ Callback Delay​

  • Payment remains in CREATED
  • Callback reconciles later

❌ Duplicate Callback​

  • Idempotency prevents duplicate updates

⚙️ Key Components​

  • PaymentController – Payment APIs
  • PaymentService – Core payment logic
  • RazorpayClientConfig – Gateway integration
  • PaymentRepository – JPA persistence
  • KafkaEventPublisher – Event publishing
  • GlobalExceptionHandler – Error handling

📈 Scalability Considerations​

  • Stateless service
  • Async callbacks via Razorpay
  • Kafka decouples post-payment workflows
  • Can handle high payment concurrency

🧪 Testing Strategy​

  • Unit tests for payment creation
  • Mock Razorpay responses
  • Callback signature validation tests
  • Failure and retry test cases

📌 Summary​

The Payment Service ensures:

  • Secure and reliable payment processing
  • Clean integration with third-party gateways
  • Event-driven extensibility
  • Accurate payment state tracking

It plays a critical role in completing the order lifecycle in ShopVerse.