Payment Microservice

The Payment Microservice provides endpoints for handling order payments, payment status checks, refunds, and webhook callbacks from external payment providers. It is designed to follow the API-First approach with an OpenAPI 3.0 specification served via Swagger UI.

---

Features

• Initiate Payment: Start a payment process and return a payment intent/link.
• Payment Status: Retrieve the status of a payment by ID.
• Webhook Handling: Accept callbacks from external payment providers.
• Refunds: Trigger refunds for existing payments.
• PATCH / DELETE (Demo Stubs): Simulated update and delete endpoints to align with sprint requirements. These do not modify real provider data — they simply acknowledge or log demo requests.

---

Tech Stack

• Framework: Node.js + Express
• Database: MySQL 8.0 (Cloud SQL)
• API Docs: Swagger UI (OpenAPI 3.0 spec)
• Language: JavaScript
• Deployment: Google Cloud Run

---

Setup

Local Development

1. Install dependencies:

   npm install

2. Start the server:

   npm start

3. Open the Swagger docs in your browser:

   http://localhost:4003/api-docs
   

Cloud Deployment

For deploying to Google Cloud Run with MySQL database, see:

• DATABASE_SETUP.md - Complete database integration guide (⭐ RECOMMENDED)
• DEPLOYMENT.md - Basic deployment without database
• QUICKSTART.md - Quick 3-step deployment guide

---

Development Mode

Run with auto-reload during development:

npm run dev

---

Project Structure

payment-microservice/
  ├── server.js              # Express app with routes + database integration
  ├── db.js                  # Database connection and query utilities
  ├── init-db.js             # Database schema initialization
  ├── db_schema.sql          # MySQL schema with seed data
  ├── package.json           # Dependencies and scripts
  ├── Dockerfile             # Container configuration for Cloud Run
  ├── deploy-with-db.sh      # Automated deployment script with Cloud SQL
  ├── openapi/
  │   └── openapi.yaml       # OpenAPI 3.0 spec
  ├── DATABASE_SETUP.md      # Complete database integration guide
  ├── DEPLOYMENT.md          # Cloud Run deployment guide
  └── README.md

---

API Documentation

Swagger UI: http://localhost:4003/api-docs

Endpoints

Payments

Method	Endpoint	Description
POST	/payments/initiate	Initiate a new payment (returns payment ID + redirect URL)
GET	/payments/{payment_id}	Get payment status/details
POST	/payments/webhook	Webhook callback from external payment provider
POST	/payments/refund/{payment_id}	Trigger a refund for a specific payment
PATCH	/payments/{payment_id}	(Demo only) Simulate partial update (e.g., metadata or client notes)
DELETE	/payments/{payment_id}	(Demo only) Simulate deletion/cancellation request for a payment

---

Example Usage (cURL)

Initiate a payment:

curl -X POST http://localhost:4003/payments/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_123",
    "amount": 4999,
    "currency": "USD",
    "method": "CARD",
    "returnUrl": "https://shop.example.com/checkout/return"
  }'

Webhook simulation:

curl -X POST http://localhost:4003/payments/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.succeeded",
    "paymentId": "pay_demo",
    "transactionRef": "tx_777",
    "amount": 4999
  }'