# Quick Reference - Payment APIs

## 🚀 Quick Start

### Initiate Payment (4 fields)
```bash
POST /api/v1/payments/initiate

{
  "client_id": "client-uuid",
  "package_id": "package-uuid", 
  "phone_number": "+254712345678",
  "description": "Payment description"
}
```

**Response:**
```json
{
  "transaction_id": "tx-uuid",
  "checkout_id": "checkout-123",
  "message": "Payment initiated successfully",
  "status": "pending"
}
```

---

### Check Payment Status
```bash
POST /api/v1/payments/status

{
  "client_id": "client-uuid",
  "checkout_id": "checkout-123"
}
```

**Response:**
```json
{
  "transaction_id": "tx-uuid",
  "checkout_id": "checkout-123",
  "status": "completed",
  "amount": 1500,
  "reference": "PKG-20260128150605-abc123",
  "phone_number": "+254712345678"
}
```

---

## 📊 Status Values

| Status | Meaning |
|--------|---------|
| `pending` | Awaiting M-Pesa confirmation |
| `completed` | Payment successful ✅ |
| `failed` | Payment failed ❌ |
| `cancelled` | User cancelled payment |

---

## ⚠️ Important Notes

1. **Phone Number**: Must be provided in the request payload
2. **No Auth Required**: Both endpoints are public
3. **Real-time Status**: Status queried directly from Safaricom
4. **Auto-update**: Local record updated with Safaricom result
4. **Validation**: Client must be active and exist in system

---

## 🔴 Error Codes

| Code | Meaning |
|------|---------|
| `400` | Bad request - invalid fields |
| `403` | Client invalid/inactive |
| `404` | Payment not found |
| `500` | Server error |

---

## 💻 JavaScript Example

```javascript
const clientId = '550e8400-e29b-41d4-a716-446655440000';
const packageId = '660e8400-e29b-41d4-a716-446655440001';
const phoneNumber = '+254712345678';

// Initiate
const initRes = await fetch('/api/v1/payments/initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: clientId,
    package_id: packageId,
    phone_number: phoneNumber,
    description: 'Internet Package'
  })
});

const { checkout_id } = await initRes.json();

// Check Status
const statusRes = await fetch('/api/v1/payments/status', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: clientId,
    checkout_id: checkout_id
  })
});

const status = await statusRes.json();
console.log('Payment Status:', status.status);
```

---

## 📝 Python Example

```python
import requests

BASE = 'http://localhost:8080/api/v1'

# Initiate
resp = requests.post(f'{BASE}/payments/initiate', json={
    'client_id': '550e8400-e29b-41d4-a716-446655440000',
    'package_id': '660e8400-e29b-41d4-a716-446655440001',
    'phone_number': '+254712345678',
    'description': 'Internet Package'
})

checkout_id = resp.json()['checkout_id']

# Check Status
status = requests.post(f'{BASE}/payments/status', json={
    'client_id': '550e8400-e29b-41d4-a716-446655440000',
    'checkout_id': checkout_id
})

print(status.json()['status'])
```

---

## 🧪 Test Data (from seeders)

**Client 1 (TechCorp Kenya):**
- ID: `1fa69aeb-568e-4a14-92ae-7b50fa75e0fe`
- Phone: `+254712345678`

**Packages for Client 1:**
- Starter (10Mbps, 500 KES): `7c92d779-a4ba-4e33-82e4-cb0d2e664ab9`
- Professional (50Mbps, 1500 KES): `681ac607-811a-4cbe-b84a-bf010d6c737b`
- Enterprise (100Mbps, 5000 KES): `44abb3ed-c9a9-4332-9ace-e11d9fb888d8`

---

## 🔄 Typical Flow

```
1. Client calls POST /payments/initiate
   ↓
2. Get checkout_id from response
   ↓
3. Customer sees M-Pesa STK prompt on phone
   ↓
4. Customer enters PIN
   ↓
5. M-Pesa processes payment
   ↓
6. System receives callback
   ↓
7. Call POST /payments/status to check result
```

---

## 📚 Full Documentation

See [docs/PUBLIC_PAYMENT_API.md](docs/PUBLIC_PAYMENT_API.md) for complete API documentation.