# PAYTR Callback Sistemi - Hızlı Başvuru Kılavuzu

## ✅ Yapılan Değişiklikler

### 1. **PaytrService.php** - Callback Metodu Güncellendi

- ✅ Hash doğrulaması iframe-step-2.md'ye göre düzeltildi
- ✅ Detaylı logging eklendi
- ✅ Idempotency (tekrar eden istekleri engelleme) eklendi
- ✅ Ek alanlar: `payment_type`, `currency`
- ✅ Hata yönetimi iyileştirildi

### 2. **PayController.php** - Response Düzeltildi

- ✅ Sadece "OK" veya "FAILED" döndürülüyor (plain text)
- ✅ iframe-step-2.md gereksinimlerine uygun
- ✅ Exception handling iyileştirildi

## 📋 Test Checklist

### 1. CSRF Exception Ekle (ÖNEMLİ!)

**Dosya:** `app/Http/Middleware/VerifyCsrfToken.php`

```php
protected $except = [
    '/pay/callback',
];
```

### 2. Test Script ile Kontrol

```bash
php test-paytr-callback.php
```

Beklenen sonuç:

- ✅ Başarılı ödeme testi → "OK"
- ✅ Başarısız ödeme testi → "FAILED"

### 3. Log Dosyasını Kontrol Et

```bash
tail -f storage/logs/laravel.log
```

Şu logları görmelisiniz:

- `PAYTR Callback received`
- `PAYTR Callback Payment Success` veya `PAYTR Callback Payment Failed`

## 🔧 PAYTR Callback Verileri

### POST Edilen Alanlar (PAYTR → Biz)

| Alan                 | Zorunlu | Açıklama                                                 |
| -------------------- | ------- | -------------------------------------------------------- |
| `merchant_oid`       | Evet    | Sipariş numarası                                         |
| `status`             | Evet    | `success` veya `failed`                                  |
| `total_amount`       | Evet    | Tahsil edilen tutar (kuruş cinsinden, 100 ile çarpılmış) |
| `hash`               | Evet    | Güvenlik hash'i                                          |
| `failed_reason_code` | Hayır   | Hata kodu (başarısız ise)                                |
| `failed_reason_msg`  | Hayır   | Hata mesajı (başarısız ise)                              |
| `test_mode`          | Hayır   | Test modu (1 veya 0)                                     |
| `payment_type`       | Evet    | `card` veya `eft`                                        |
| `currency`           | Evet    | `TL`, `USD`, `EUR`, vb.                                  |
| `payment_amount`     | Evet    | Orijinal sipariş tutarı                                  |

### Hash Formülü (DOĞRU)

```php
$hashString = $data['merchant_oid'] . $this->merchantSalt . $data['status'] . $data['total_amount'];
$hash = base64_encode(hash_hmac('sha256', $hashString, $this->merchantKey, true));
```

**Örnek:**

```php
$merchantOid = 'PAY123456';
$merchantSalt = 'urxA5iL4EdoN8bx3';
$status = 'success';
$totalAmount = 245000; // 2,450.00 TL

$hashString = 'PAY123456' . 'urxA5iL4EdoN8bx3' . 'success' . 245000;
// Hash string: PAY123456urxA5iL4EdoN8bx3success245000

$hash = base64_encode(hash_hmac('sha256', $hashString, 'Y2MW4s2ZkFYMGspG', true));
```

### Response (Biz → PAYTR)

- ✅ Başarılı: `"OK"` (plain text, JSON değil!)
- ✅ Başarısız: `"FAILED"` (plain text, JSON değil!)

## 🚀 Production Deployment

### 1. Callback URL Ayarla

PAYTR Mağaza Paneli → Destek & Kurulum → AYARLAR

```
Bildirim URL: https://yourdomain.com/pay/callback
```

### 2. HTTPS Kullan

Production'da mutlaka HTTPS kullanın.

### 3. Firewall Ayarları

PAYTR IP adreslerini whitelist'e ekleyin (gerekirse).

### 4. Monitoring

Log dosyasını düzenli olarak kontrol edin:

```bash
grep "PAYTR Callback" storage/logs/laravel.log
```

## ⚠️ Yaygın Hatalar

### ❌ Hash Uyuşmazlığı

**Sebep:** Yanlış hash formülü  
**Çözüm:** `merchant_oid + merchant_salt + status + total_amount`

### ❌ CSRF Token Hatası

**Sebep:** Middleware koruması  
**Çözüm:** `/pay/callback` rotasını CSRF exception'a ekle

### ❌ Yanlış Response Formatı

**Sebep:** JSON veya HTML döndürmek  
**Çözüm:** Sadece plain text "OK" veya "FAILED" döndür

### ❌ Duplicate Processing

**Sebep:** Idempotency kontrolü yok  
**Çözüm:** Payment status kontrolü ile tekrar işleme engel ol

## 📊 Log Örnekleri

### Başarılı Ödeme

```
[timestamp] local.INFO: PAYTR Callback received {"data":{...},"ip":"127.0.0.1"}
[timestamp] local.INFO: PAYTR Callback Payment Success {"merchant_oid":"PAY123","total_amount":245000}
```

### Hash Hatası

```
[timestamp] local.ERROR: PAYTR Callback Hash Mismatch {"expected_hash":"...","received_hash":"..."}
```

### Duplicate Request

```
[timestamp] local.INFO: PAYTR Callback Duplicate Request Skipped {"merchant_oid":"PAY123","current_status":"success"}
```

## 🔍 Sorun Giderme

### 1. Callback gelmiyor mu?

- PAYTR panelinde callback URL doğru mu?
- Firewall/PAYTR IP engelleme var mı?
- HTTPS kullanılıyor mu?

### 2. Hash uyuşmuyor mu?

- Merchant salt/key doğru mu?
- total_amount kuruş cinsinden mi (100 ile çarpılmış)?
- String concatenation doğru mu?

### 3. Response gitmiyor mu?

- Plain text mi dönüyorsunuz? (JSON değil)
- Sadece "OK" veya "FAILED" mı?
- HTTP status code 200 mü?

## 📞 Destek

Sorun yaşarsanız:

1. Log dosyasını kontrol edin (`storage/logs/laravel.log`)
2. Test script'i çalıştırın (`php test-paytr-callback.php`)
3. PAYTR dökümanlarını tekrar okuyun (`resources/paytr/iframe-step-2.md`)