Skip to main content

Payment Service – API Reference 💳

This document describes the payment-related APIs exposed by the Payment Service in ShopVerse.

Payments are handled securely using Razorpay and all APIs are accessed via the API Gateway.

🌐 Base URL​


/api/payments

🔐 Authentication & Authorization​

  • JWT is validated at the API Gateway
  • Gateway injects:
    • X-User-Email
    • X-User-Role
  • Only authenticated users can initiate payments
  • Admin access is restricted to reporting APIs

💰 Create Payment Order​

Initiate a payment for an existing order.

➤ Endpoint​


POST /api/payments/create

➤ Request Body​

{
  "orderId": "ORD789",
  "amount": 5497
}

➤ Success Response (200 OK)​

{
  "razorpayOrderId": "order_JH23KLM",
  "amount": 5497,
  "currency": "INR"
}

📄 Get My Payments​

Fetch payment history of the authenticated user.

➤ Endpoint​

GET /api/payments/my

➤ Success Response (200 OK)​

[
  {
    "paymentId": "PAY123",
    "orderId": "ORD789",
    "amount": 5497,
    "status": "SUCCESS",
    "createdAt": "2026-01-21T12:45:00"
  }
]

🔔 Payment Callback (Webhook)​

Handle Razorpay payment callbacks.

This endpoint is internal and not exposed to clients.

➤ Endpoint​

POST /api/payments/callback

➤ Headers​

X-Razorpay-Signature

➤ Callback Payload (Example)​

{
  "razorpay_payment_id": "pay_JH23XYZ",
  "razorpay_order_id": "order_JH23KLM",
  "razorpay_signature": "abc123signature"
}

➤ Success Response (200 OK)​

{
  "message": "Payment processed successfully"
}

🔄 Payment Lifecycle​

📡 Events Published​

EventTopicDescription
PAYMENT_CREATEDpayment-eventsPayment initiated
PAYMENT_SUCCESSpayment-eventsPayment successful
PAYMENT_FAILEDpayment-eventsPayment failed

Consumed by:

  • Order Service
  • Notification Service
  • Analytics Service

🔄 Request Flow​

⚠️ Common Errors​

StatusMeaning
400Invalid payment request
401Unauthorized
403Forbidden
404Order not found
500Payment gateway failure

🛡️ Security Notes​

  • Razorpay signatures are verified
  • Payment secrets stored in environment variables
  • Callbacks are idempotent
  • Duplicate callbacks are safely ignored

📌 Summary​

The Payment API provides:

  • Secure payment initiation
  • Reliable callback handling
  • Event-driven post-payment workflows
  • Clean integration with Razorpay

It ensures safe and consistent payment processing in ShopVerse.