docs/payment-workflow.md

# Payment Workflow

## Overview

- **Provider**: Stripe
- **Commission**: Platform 15% | Sheikh 85%
- **Currency**: USD

## Payment Status Lifecycle

```
                ┌─────────┐
                │ PENDING │  ← PaymentIntent created
                └────┬────┘
                     │
          ┌──────────┴──────────┐
          │ Stripe succeeds     │ Stripe fails / expires
          ▼                     ▼
       ┌──────┐             ┌────────┐
       │ PAID │             │ FAILED │ → Can retry
       └───┬──┘             └────────┘
           │
           │ Session COMPLETED
           │ Sheikh payout triggered
           ▼
     ┌────────────┐
     │ PAYOUT_DONE│
     └────────────┘

  PAID/PENDING → REFUNDED  (session MISSED or CANCELLED)
```

---

## Phase 1 — Initiate Payment

**Trigger**: Student clicks "Pay Now" on a TOPAY session  
**Component**: `StripePaymentModal.tsx`

```
POST /api/payments/initiate/card
{
  "sessionId": 123,
  "studentId": 45,
  "sheikhId": 67,
  "amount": 50.00
}
```

**Backend logic** (`PaymentServiceStripe.java`):

```
Receive request
      │
      ▼
Check existing Payment record for this session
      │
      ├── PAID / PAYOUT_DONE  → Reject (already paid)
      ├── PENDING             → Return existing PaymentIntent (idempotent)
      ├── FAILED / REFUNDED   → Delete old record, create new
      └── No record           → Create new
            │
            ▼
      Create Stripe PaymentIntent
      amount = 5000 cents (USD)
            │
            ▼
      Save Payment record:
        amount:             $50.00
        platformCommission: $7.50  (15%)
        sheikhPayout:       $42.50 (85%)
        paymentStatus:      PENDING
        transactionId:      pi_xxxxx
            │
            ▼
      Return to frontend:
        { clientSecret, publishableKey, paymentIntentId }
```

---

## Phase 2 — Frontend Stripe Checkout

**Component**: `StripePaymentModal.tsx`

```
Load Stripe.js with publishableKey
        │
        ▼
Mount Stripe CardElement (secure iframe)
        │
        ▼
User enters card details
        │
        ▼
stripe.confirmCardPayment(clientSecret, {
  payment_method: { card: cardElement }
})
        │
        ├── success → proceed to Phase 3
        └── error   → show error to user (can retry)
```

---

## Phase 3 — Confirm Payment (Backend)

```
POST /api/payments/confirm-payment/{paymentIntentId}
        │
        ▼
Backend retrieves PaymentIntent from Stripe API
        │
        ├── status: "succeeded" / "requires_capture"
        │       │
        │       ▼
        │   Payment record → PAID
        │   Session status → SCHEDULED
        │   Return success to frontend
        │
        ├── status: "processing"
        │       │
        │       ▼
        │   Keep PENDING (Stripe webhook handles later)
        │
        └── other status
                │
                ▼
            Payment record → FAILED
            Throw error
```

---

## Phase 4 — Payout to Sheikh

**Trigger**: Sheikh calls `POST /api/sheikh/sessions/{id}/end`  
**Automatic — no manual action needed**

```
Session ends → status: COMPLETED
        │
        ▼
paymentServiceStripe.payoutSheikh(sessionId)
        │
        ▼
Validate payment is PAID
        │
        ▼
Validate sheikh has Stripe connected account
(sheikhProfile.stripeAccountId)
        │
        ▼
Create Stripe Transfer:
  amount:      $42.50  (85% of $50.00)
  destination: sheikh's Stripe account ID
        │
        ▼
Payment record → PAYOUT_DONE
Transfer ID saved
        │
        ▼
Funds arrive in sheikh's bank within 1–2 business days

> If transfer fails: error is logged, session stays COMPLETED
> Sheikh contacts support for manual payout
```

---

## Refund Scenarios

| Scenario | Trigger | Result |
|---|---|---|
| Session MISSED — no-show | Auto, 10 min after start | Full refund to student |
| Session auto-cancelled (unpaid) | Auto, 5 min before start | No charge (PaymentIntent voided) |
| Sheikh manually rejects | Sheikh clicks Reject | Full refund if already paid |

**Refund Flow**:

```
POST /api/payments/refund/{sessionId}
        │
        ▼
Check payment status
        │
        ├── PENDING (not captured yet)
        │       │
        │       └── Mark REFUNDED locally (no Stripe call needed)
        │
        └── PAID
                │
                ▼
            Create Stripe Refund
            amount: full original charge
                │
                ▼
            Payment record → REFUNDED
            Refund timestamp saved
```

---

## Commission Split Diagram

```
Student pays $50.00
        │
        ▼
┌───────────────────────────────────┐
│         Platform Account          │
│                                   │
│   $7.50  (15%) Platform fee       │
│   $42.50 (85%) → Sheikh payout    │
└──────────────────┬────────────────┘
                   │ Stripe Transfer (on session complete)
                   ▼
         Sheikh's Stripe Account
              $42.50
```

> Commission percentage is configurable via `platform.commission.percentage` in `application.yaml` (default: 15%)

---

## API Endpoints Reference

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/payments/initiate/card` | Create PaymentIntent, return clientSecret |
| POST | `/api/payments/confirm-payment/{paymentIntentId}` | Confirm payment after Stripe.js success |
| POST | `/api/payments/confirm-session/{sessionId}` | Sheikh accepts — verify payment is PAID |
| POST | `/api/payments/payout/{sessionId}` | Payout sheikh (called automatically on session end) |
| POST | `/api/payments/refund/{sessionId}` | Refund student |

---

## Key Notes

- **Idempotent**: Calling initiate twice for the same session returns the existing PaymentIntent — no duplicate charges.
- **No double-pay**: Backend checks for existing PAID/PAYOUT_DONE records and rejects the request.
- **Auto-retry safe**: FAILED/REFUNDED records are deleted and a fresh PaymentIntent is created on retry.
- **Payout is non-blocking**: A failed Stripe Transfer does not roll back the COMPLETED session status.