feat: implement platform treasury model with merchant balance tracking and API docs

API_DOCS.md

@@ -0,0 +1,93 @@
+# 📡 Pay2Gateway API v1 Kullanım Rehberi
+
+Pay2Gateway API, firmaların (merchants) kendi sistemlerini bizim ödeme geçidimize entegre etmelerini sağlar. Tüm istekler JSON formatında yapılmalı ve geçerli bir API anahtarı içermelidir.
+
+## 🔑 Kimlik Doğrulama (Authentication)
+Tüm API isteklerinde `x-api-key` header'ı zorunludur. API anahtarınızı Merchant Panel -> Ayarlar kısmından alabilirsiniz.
+
+**Örnek Header:**
+```http
+x-api-key: gwa_live_xxxxxxxxxxxx
+Content-Type: application/json
+```
+
+---
+
+## 🛒 1. Ödeme Oturumu Oluşturma (Checkout Session)
+Bir müşteri ödeme yapmak istediğinde, sunucunuzdan bu endpoint'e istek atarak bir ödeme oturumu oluşturun.
+
+- **Endpoint:** `POST /api/v1/checkout`
+- **Açıklama:** Yeni bir işlem başlatır ve müşteriyi yönlendirebileceğiniz bir URL döndürür.
+
+### İstek Gövdesi (Request Body)
+| Parametre | Tip | Zorunlu mu? | Açıklama |
+| :--- | :--- | :--- | :--- |
+| `amount` | Float | Evet | Tahsil edilecek tutar. |
+| `currency` | String | Hayır | Para birimi (Varsayılan: `TRY`). |
+| `order_id` | String | Evet | Kendi sisteminizdeki sipariş numarası. |
+| `customer_name` | String | Hayır | Müşterinin adı. |
+| `customer_phone` | String | Hayır | Müşterinin telefon numarası. |
+| `callback_url` | String | Hayır | Ödeme sonrası sunucunuza bildirim atılacak URL. |
+| `success_url` | String | Hayır | Başarılı ödeme sonrası kullanıcının döneceği URL. |
+| `cancel_url` | String | Hayır | İptal edilen ödeme sonrası kullanıcının döneceği URL. |
+
+**Örnek İstek:**
+```json
+{
+  "amount": 1250.50,
+  "currency": "TRY",
+  "order_id": "SİPARİŞ_102",
+  "customer_name": "Ahmet Yılmaz",
+  "callback_url": "https://siteniz.com/api/webhooks/pay2gateway",
+  "success_url": "https://siteniz.com/payment/success",
+  "cancel_url": "https://siteniz.com/payment/cancel"
+}
+```
+
+### Yanıt (Response)
+Başarılı bir istek sonucunda `checkout_url` döndürülür. Müşterinizi bu adrese yönlendirmeniz yeterlidir.
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid-islem-id",
+    "checkout_url": "https://pay2gateway.com/checkout?session_id=uuid-islem-id",
+    "status": "pending",
+    "wallets": {
+      "EVM": "0x...",
+      "SOLANA": "...",
+      "TRON": "...",
+      "BITCOIN": "..."
+    }
+  }
+}
+```
+
+---
+
+## 🔔 2. Webhook Bildirimleri
+Ödeme tamamlandığında veya blockchain üzerinde onaylandığında, `callback_url` adresine bir `POST` isteği gönderilir.
+
+**Webhook Gövdesi:**
+```json
+{
+  "status": "success",
+  "amount": 1250.50,
+  "currency": "TRY",
+  "ref_id": "SİPARİŞ_102",
+  "tx_hash": "0xabc123...",
+  "network": "POLYGON",
+  "token": "USDT"
+}
+```
+
+---
+
+## 🛡️ Güvenlik Notları
+- **API Key:** API anahtarınızı asla frontend kodlarınızda (JavaScript/React) paylaşmayın. Sadece sunucu tarafında kullanın.
+- **İşlem Doğrulama:** Webhook geldiğinde tutarı ve sipariş ID'sini kendi veritabanınızla karşılaştırın.
+- **Test Modu:** Test yapmak için admin panelinden `MOCK_PAYMENTS` ayarını aktif edebilirsiniz.
+
+---
+⭐ **Pay2Gateway Support** - Teknik destek için `support@ayris.dev` üzerinden bize ulaşabilirsiniz.