💳 Payment Service

Multi-provider payment processing microservice for the xshopai e-commerce platform

Getting Started • Documentation • API Reference • Contributing

---

🎯 Overview

The Payment Service handles payment transactions, refunds, and payment method management across multiple providers (Stripe, PayPal, Square). Built with a provider abstraction layer, it supports multi-currency operations, PCI compliance considerations, and idempotent payment processing with full audit trails.

---

✨ Key Features

💳 Multi-Provider Payments Stripe, PayPal, and Square integration Provider abstraction layer Multi-currency support (USD, EUR, GBP, CAD) Idempotent payment processing	🔄 Refund Management Full and partial refunds Refund reason tracking Provider-specific refund handling Refund status monitoring
💾 Payment Methods Secure payment method storage Customer payment profiles Default method selection Provider tokenization	🛡️ Security & Compliance PCI compliance considerations JWT Bearer authentication Provider credential security Complete transaction audit trails

---

🚀 Getting Started

Prerequisites

• .NET 8 SDK
• SQL Server 2019+
• Docker & Docker Compose (optional)
• Dapr CLI (for production-like setup)

Quick Start with Docker Compose

# Clone the repository
git clone https://github.com/xshopai/payment-service.git
cd payment-service

# Start SQL Server + service
docker-compose up -d

# Verify the service is healthy
curl http://localhost:8009/health

Local Development Setup

🔧 Without Dapr (Simple Setup)

# Restore dependencies
dotnet restore

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start SQL Server (Docker)
docker-compose -f docker-compose.db.yml up -d

# Apply migrations
dotnet ef database update --project PaymentService

# Run the service
dotnet run --project PaymentService

📖 See Local Development Guide for detailed instructions.

⚡ With Dapr (Production-like)

# Ensure Dapr is initialized
dapr init

# Start with Dapr sidecar
./run.sh       # Linux/Mac
.\run.ps1      # Windows

# Or manually
dapr run \
  --app-id payment-service \
  --app-port 8009 \
  --dapr-http-port 3500 \
  --dapr-grpc-port 50001 \
  --resources-path .dapr/components \
  --config .dapr/config.yaml \
  -- dotnet run --project PaymentService

Note: All services now use the standard Dapr ports (3500 for HTTP, 50001 for gRPC).

---

📚 Documentation

Document	Description
📘 Local Development	Step-by-step local setup and development workflows
📘 Technical Reference	Architecture, security, monitoring
☁️ Azure Container Apps	Deploy to serverless containers with built-in Dapr

API Documentation: Swagger UI available at /swagger endpoint.

---

🔌 API Reference

Payments

Method	Endpoint	Description
POST	/api/payments	Process a payment
GET	/api/payments	Get payments (filtered)
GET	/api/payments/{id}	Get specific payment
POST	/api/payments/{id}/refund	Process refund
GET	/api/payments/order/{orderId}	Get payment by order

Payment Methods

Method	Endpoint	Description
POST	/api/paymentmethods	Save payment method
GET	/api/paymentmethods/customer/{customerId}	Customer's methods
DELETE	/api/paymentmethods/{id}	Delete payment method
GET	/api/paymentmethods/supported-methods	Supported methods
GET	/api/paymentmethods/providers	Available providers
GET	/api/paymentmethods/providers/{name}/status	Provider status

---

🧪 Testing

# Run all tests
dotnet test

# Build without tests
dotnet build

# Run with specific configuration
dotnet test --configuration Release

# Apply migration
dotnet ef database update --project PaymentService

Provider Testing

Provider	Test Mode
Stripe	Test card: 4242424242424242
PayPal	Sandbox environment
Square	Sandbox environment

---

🏗️ Project Structure

payment-service/
├── 📁 PaymentService/               # Main application project
│   ├── 📁 Controllers/              # REST API endpoints
│   ├── 📁 Services/                 # Business logic + provider adapters
│   ├── 📁 Models/
│   │   ├── 📁 Entities/             # Domain entities (Payment, Refund)
│   │   └── 📁 DTOs/                 # Data transfer objects
│   ├── 📁 Data/                     # EF Core context + migrations
│   ├── 📁 Configuration/            # Settings classes
│   └── 📄 Program.cs                # Application entry point
├── 📁 PaymentService.Tests/         # Unit tests
├── 📁 docs/                         # Documentation
├── 📁 .dapr/                        # Dapr configuration
│   ├── 📁 components/               # Pub/sub, state stores
│   └── 📄 config.yaml               # Dapr runtime configuration
├── 📄 docker-compose.yml            # Full service stack
├── 📄 docker-compose.db.yml         # SQL Server only
├── 📄 Dockerfile                    # Production container image
└── 📄 PaymentService.sln            # Solution file

---

🔧 Technology Stack

Category	Technology
🟣 Runtime	.NET 8 / C# 12
🌐 Framework	ASP.NET Core 8
🗄️ Database	SQL Server 2022 with Entity Framework Core
💳 Providers	Stripe, PayPal, Square (pluggable)
📨 Messaging	Dapr Pub/Sub (RabbitMQ backend)
🔐 Authentication	JWT Bearer Tokens
📖 API Docs	Swagger / OpenAPI (Swashbuckle)
🧪 Testing	xUnit
📊 Observability	Structured logging + correlation IDs

---

⚡ Quick Reference

# 🐳 Docker Compose
docker-compose up -d              # Start all services
docker-compose down               # Stop all services
docker-compose -f docker-compose.db.yml up -d  # SQL Server only

# 🟣 Local Development
dotnet run --project PaymentService  # Run service
dotnet watch --project PaymentService  # Hot reload

# ⚡ Dapr Development
./run.sh                          # Linux/Mac
.\run.ps1                         # Windows

# 🧪 Testing
dotnet test                       # Run all tests
dotnet build                      # Build solution

# 🔍 Health Check
curl http://localhost:8009/health
curl http://localhost:8009/swagger

---

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Write tests for your changes
4. Run the test suite

   dotnet test

5. Commit your changes

   git commit -m 'feat: add amazing feature'

6. Push to your branch

   git push origin feature/amazing-feature

7. Open a Pull Request

Please ensure your PR:

• ✅ Passes all existing tests
• ✅ Includes tests for new functionality
• ✅ Follows PCI compliance considerations
• ✅ Updates documentation as needed

---

🆘 Support

Resource	Link
🐛 Bug Reports	GitHub Issues
📖 Documentation	docs/
💬 Discussions	GitHub Discussions

---

📄 License

This project is part of the xshopai e-commerce platform. Licensed under the MIT License - see LICENSE for details.

---

⬆ Back to Top

Made with ❤️ by the xshopai team