# API Documentation

## Overview
This document provides comprehensive API documentation for the KiyoKart e-commerce application.

## Base URL
```
https://your-domain.com/api
```

## Authentication
Most endpoints require authentication. Use Laravel Sanctum for API authentication.

## Endpoints

### Webhooks

#### Razorpay Webhook
**POST** `/api/webhooks/razorpay`

Handles Razorpay payment webhook events.

**Headers:**
- `X-Razorpay-Signature`: Webhook signature (required if webhook secret is configured)

**Events Supported:**
- `payment.authorized` - Payment authorized
- `payment.captured` - Payment captured
- `payment.failed` - Payment failed
- `payment.refunded` - Payment refunded
- `refund.created` - Refund created

**Response:**
```json
{
    "status": "success"
}
```

---

## Error Responses

All error responses follow this format:

```json
{
    "error": "Error message",
    "context": {
        // Additional context data
    }
}
```

### Status Codes
- `200` - Success
- `400` - Bad Request
- `401` - Unauthorized
- `404` - Not Found
- `429` - Too Many Requests (Rate Limited)
- `500` - Internal Server Error

---

## Rate Limiting

### OTP Endpoints
- **Request OTP**: 3 requests per 15 minutes per mobile/IP
- **Verify OTP**: 5 attempts per 15 minutes per mobile/IP

---

## Webhook Security

Razorpay webhooks use signature verification. Configure `RAZORPAY_WEBHOOK_SECRET` in your `.env` file.