# API Documentation

## Project
Advanced API-Based Payment Gateway System

## Base URL
https://yourdomain.com/api/v1

## Content Type
application/json

## Authentication
All client APIs must use:
- API Key
- Secret Key
- HMAC Signature
- Timestamp
- Nonce

---

## 1. Authentication Headers

```http
X-API-KEY: client_api_key
X-API-SIGNATURE: generated_signature
X-API-TIMESTAMP: 1719999999
X-API-NONCE: random_string
```

---

## 2. Common API Rules

- All requests must use HTTPS.
- All requests must be JSON.
- Timestamp should not be older than 5 minutes.
- Signature must match server-generated hash.
- Duplicate nonce requests should be rejected.
- Rate limiting must be applied per client.

---

## 3. Signature Generation

### Input format
```text
HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + RAW_JSON_BODY
```

### Example
```php
$payload = $method . "\n" . $path . "\n" . $timestamp . "\n" . $nonce . "\n" . $body;
$signature = hash_hmac('sha256', $payload, $secret_key);
```

---

## 4. Endpoints

---

### 4.1 Create Payment
**POST** `/pay`

Creates a new payment transaction.

#### Request Body
```json
{
  "order_id": "ORD-10001",
  "amount": 1500.00,
  "currency": "INR",
  "customer_name": "Rahul Kumar",
  "customer_email": "rahul@example.com",
  "customer_phone": "9999999999",
  "return_url": "https://client.com/success",
  "webhook_url": "https://client.com/webhook",
  "metadata": {
    "product_id": "P100",
    "notes": "Test order"
  }
}
```

#### Response
```json
{
  "success": true,
  "message": "Payment created successfully",
  "data": {
    "transaction_id": "txn_abc123",
    "order_id": "ORD-10001",
    "amount": 1500.00,
    "currency": "INR",
    "status": "pending",
    "payment_url": "https://yourdomain.com/pay/txn_abc123"
  }
}
```

---

### 4.2 Get Payment Status
**GET** `/transaction/{transaction_id}`

#### Response
```json
{
  "success": true,
  "data": {
    "transaction_id": "txn_abc123",
    "order_id": "ORD-10001",
    "amount": 1500.00,
    "currency": "INR",
    "status": "success",
    "payment_method": "gateway_x",
    "created_at": "2026-06-18 20:00:00"
  }
}
```

---

### 4.3 List Transactions
**GET** `/transactions`

#### Query Params
- page
- limit
- status
- order_id
- from_date
- to_date

#### Response
```json
{
  "success": true,
  "data": [
    {
      "transaction_id": "txn_abc123",
      "order_id": "ORD-10001",
      "amount": 1500.00,
      "status": "success"
    }
  ]
}
```

---

### 4.4 Refund Payment
**POST** `/refund`

#### Request Body
```json
{
  "transaction_id": "txn_abc123",
  "amount": 500.00,
  "reason": "Customer request"
}
```

#### Response
```json
{
  "success": true,
  "message": "Refund request submitted",
  "data": {
    "refund_id": "ref_001",
    "status": "pending"
  }
}
```

---

### 4.5 Webhook Receiver
**POST** `/webhook`

Used by gateways to send status updates.

#### Webhook Event Types
- payment.success
- payment.failed
- payment.pending
- payment.refunded
- payment.disputed

#### Example Payload
```json
{
  "event": "payment.success",
  "transaction_id": "txn_abc123",
  "order_id": "ORD-10001",
  "amount": 1500.00,
  "currency": "INR",
  "status": "success",
  "gateway_ref": "gw_9981",
  "timestamp": "2026-06-18T20:10:00Z"
}
```

#### Webhook Security
- Validate signature
- Verify source
- Log all attempts
- Retry failed deliveries

---

### 4.6 Regenerate API Keys
**POST** `/api-keys/regenerate`

#### Request Body
```json
{
  "client_id": 1
}
```

#### Response
```json
{
  "success": true,
  "message": "API keys regenerated",
  "data": {
    "api_key": "new_api_key",
    "secret_key": "new_secret_key"
  }
}
```

---

### 4.7 Client Profile
**GET** `/client/profile`

Returns client account summary.

---

### 4.8 Client Dashboard Stats
**GET** `/client/dashboard`

Returns:
- total transactions
- total success
- total failed
- total amount
- commission amount

---

### 4.9 Gateway List
**GET** `/gateways`

Returns active gateways.

---

### 4.10 Gateway Health
**GET** `/gateways/health`

Returns gateway status and uptime.

---

## 5. Error Responses

### Invalid Signature
```json
{
  "success": false,
  "message": "Invalid signature",
  "code": 401
}
```

### Validation Error
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount is required"]
  },
  "code": 422
}
```

### Rate Limited
```json
{
  "success": false,
  "message": "Too many requests",
  "code": 429
}
```

---

## 6. Status Codes

- 200 OK
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 422 Validation Error
- 429 Too Many Requests
- 500 Internal Server Error

---

## 7. Request Validation Rules

- amount must be greater than 0
- currency must be valid ISO code
- order_id must be unique per client
- customer_email must be valid
- webhook_url must be HTTPS
- return_url must be valid URL

---

## 8. Webhook Retry Logic

- Retry after 1 minute
- Retry after 5 minutes
- Retry after 15 minutes
- Maximum 3 retries
- Mark failed after max retries

---

## 9. Logging Requirements

Every API request must log:
- client_id
- endpoint
- request body
- response body
- status code
- IP address
- timestamp

---

## 10. Versioning

All APIs should be versioned:
- /api/v1/pay
- /api/v1/webhook
- /api/v1/transactions

Future breaking changes should use /api/v2/ path.