# Payment Service — Detailed Design

| Field | Value |
|-------|-------|
| Document ID | DD-PAYMENT-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |

---

## 1. Service Overview

The Payment Service handles payment processing for individual orders. It validates payment amounts, enforces business rules, processes transactions, and notifies Order Service of payment status via webhook callbacks.

---

## 2. API Endpoints

### 2.1 POST /api/v1/payments/ — Create Payment

Processes payment for a **SINGLE** order. No batch payment processing.

**Request:**
```json
{"order_id": 1, "amount": 89800.0, "currency": "JPY"}
```

**Validation:**
- `amount` >= 100 JPY (minimum)
- `amount` <= 1,000,000 JPY (maximum per single transaction)
- `order_id` must be unique (no duplicate payments)

### 2.2 GET /api/v1/payments/{payment_id}

### 2.3 GET /api/v1/payments/order/{order_id}

Returns payment for a specific order (1:1 relationship).

### 2.4 POST /api/v1/payments/refund

**Request:** `{"payment_id": 1, "reason": "Order cancelled by customer"}`

### 2.5 POST /api/v1/payments/webhook

Receives external payment gateway callbacks.

---

## 3. Data Model

```mermaid
erDiagram
    payments {
        int id PK
        int order_id UK "UNIQUE - one payment per order"
        float amount
        string currency "JPY"
        enum status "PENDING|PROCESSING|COMPLETED|FAILED|REFUNDED"
        string payment_method "credit_card"
        string transaction_id UK
        datetime created_at
        datetime updated_at
    }
    refunds {
        int id PK
        int payment_id FK
        float amount
        string reason
        string status
        datetime created_at
    }
    payments ||--o{ refunds : "has"
```

> **Schema Constraint:** `order_id` has a UNIQUE constraint enforcing a **1:1 payment-to-order relationship**. This means there is no way to create a batch payment that covers multiple orders. Each order must have its own individual payment record.

> **No batch fields:** There is no `batch_id`, `bulk_payment_group`, or `aggregated_amount` column. The schema is designed exclusively for single-order payments.

---

## 4. Payment Processing Flow

```mermaid
sequenceDiagram
    participant OS as Order Service
    participant PS as Payment Service
    participant DB as Payment DB

    OS->>PS: POST /api/v1/payments
    Note over PS: Validate amount (100 - 1,000,000 JPY)
    Note over PS: Check duplicate order_id
    PS->>DB: INSERT payment (status: PROCESSING)
    Note over PS: Simulate payment processing
    PS->>DB: UPDATE payment (status: COMPLETED)
    PS-->>OS: 201 Created
```

---

## 5. Business Rules

| Rule | Description | Value |
|------|-------------|-------|
| Minimum amount | Per-transaction minimum | 100 JPY |
| Maximum amount | Per-transaction maximum | **1,000,000 JPY** |
| Order relationship | Payment-to-order cardinality | **1:1 (unique constraint)** |
| Duplicate check | Same order_id rejected | Error 400 |
| Refund scope | Full refund only | Refund amount = payment amount |

### 5.1 Amount Validation Impact on Bulk Operations

The maximum amount of 1,000,000 JPY applies **per single transaction**. If a bulk order import feature were added:
- Individual orders under 1,000,000 JPY would each need their own payment call
- There is no aggregated or batch payment endpoint to process multiple orders in one transaction
- Processing 10,000 orders would require 10,000 individual payment API calls

---

## 6. Webhook Mechanism

After payment processing, Payment Service calls Order Service to update order status:

```
POST http://localhost:8000/api/v1/orders/{order_id}/webhook
Body: {"payment_status": "completed", "transaction_id": "uuid"}
```

This is a **single-order callback**. No batch webhook or batch status update exists.

---

## 7. Current Limitations

| ID | Limitation | Severity |
|----|-----------|----------|
| DD-PAY-LIM-001 | **Only processes ONE order at a time.** No bulk/batch payment API exists. | High |
| DD-PAY-LIM-002 | **No aggregated amount calculation.** Cannot combine multiple order amounts into a single transaction. | High |
| DD-PAY-LIM-003 | **Maximum 1,000,000 JPY per single transaction.** This limit applies per-order; bulk orders with individual amounts above this limit would be rejected. | Medium |
| DD-PAY-LIM-004 | **1:1 payment-to-order unique constraint prevents batch payment grouping.** Cannot create a single payment record covering multiple orders. | High |
| DD-PAY-LIM-005 | **Single-order webhook callback.** No mechanism to batch-notify Order Service of multiple payment completions. | Medium |
| DD-PAY-LIM-006 | **No payment queue or async processing.** All payments are processed synchronously in the request thread. | Medium |