# 📡 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.