# Kuveyt Türk 3D Secure 2.0 Entegrasyonu - Kullanım Kılavuzu

## Yapılan Değişiklikler

### 1. **IP Adresi Sorunu Çözüldü** ✅
- Müşterinin gerçek IP adresi (`ClientIP`) artık otomatik olarak alınıyor
- `request()->ip()` kullanılarak her işlemde dinamik olarak ekleniyor
- Statik IP tanımlamasına gerek yok

### 2. **API Güncellendi** ✅
- Eski HTML form POST yöntemi kaldırıldı
- Yeni 3D Secure 2.0 standardına uygun XML formatı kullanılıyor
- `APIVersion: TDV2.0.0` ile güncel API kullanılıyor

### 3. **HashData Sorunu Düzeltildi** ✅
- Doğru hash hesaplama algoritması: `base64_encode(pack('H*', sha1($data)))`
- URL'lerde `&` karakteri varsa `&` olarak değiştiriliyor
- Debug log'ları eklendi

### 4. **Yeni Zorunlu Alanlar Eklendi** ✅
- `DeviceChannel`: Web tarayıcı için "02"
- `ClientIP`: Müşterinin IP adresi
- `CardHolderName`: Kart sahibi adı
- `Email`: Müşteri email
- `BillAddrCity`, `BillAddrCountry`, `BillAddrLine1`, `BillAddrPostCode`, `BillAddrState`: Fatura adresi bilgileri
- `MobilePhone` (Cc ve Subscriber): Telefon bilgileri

## Kullanım

### 1. Ödeme Başlatma (GeneratePayment)

```php
use App\PaymentSystem\Kuveytturk\GeneratePayment;

// Ödeme işlemi oluştur
$payment = new GeneratePayment($userReq, $user, $address, $cart, $amount, $card);
$payment->setSettings($settings);

// Ödeme formunu oluştur
$result = $payment->generate($orderId);

if ($result) {
    // Bankaya yönlendirme HTML'i
    echo $payment->getHtml();
}
```

### 2. Callback İşleme (CallbackHandler)

Controller'ınızda callback'i işleyin:

```php
use App\PaymentSystem\Kuveytturk\CallbackHandler;

public function paymentCallback(Request $request)
{
    // Settings'i al
    $settings = [
        'kuveytturk_merchant_id' => '529530', // Örnek
        'kuveytturk_customer_name' => '400235', // Örnek
        'kuveytturk_username' => 'apitest',
        'kuveytturk_password' => 'api123',
        'mode' => '1' // 1: Test, 0: Production
    ];

    $handler = new CallbackHandler($settings);
    
    // 1. Kart doğrulama sonucunu işle
    $result = $handler->handleCallback($request);
    
    if ($result['success'] && $result['needsProvision']) {
        // 2. Provizyon al (ödemeyi tamamla)
        $provision = $handler->getProvision(
            $result['merchantOrderId'],
            $amount, // TL cinsinden (örn: 100.50)
            $result['md']
        );
        
        if ($provision['success']) {
            // ✅ ÖDEME BAŞARILI
            // Order'ı onayla, stok düş vs.
            
            return response()->json([
                'success' => true,
                'message' => 'Ödeme başarılı',
                'provisionNumber' => $provision['provisionNumber'],
                'orderId' => $provision['orderId']
            ]);
        } else {
            // ❌ Provizyon alınamadı
            return response()->json([
                'success' => false,
                'message' => $provision['message']
            ]);
        }
    } else {
        // ❌ Kart doğrulama başarısız
        return response()->json([
            'success' => false,
            'message' => $result['message']
        ]);
    }
}
```

## Ayarlar (Settings Array)

```php
$settings = [
    'kuveytturk_merchant_id' => 'XXXX', // Banka tarafından verilen Merchant ID
    'kuveytturk_customer_name' => 'XXXX', // Banka tarafından verilen Customer ID
    'kuveytturk_username' => 'XXXX', // API kullanıcı adı
    'kuveytturk_password' => 'XXXX', // API şifresi
    'mode' => '1' // 1: Test ortamı, 0: Production
];
```

## Test Bilgileri

### Test Ortamı
```
CustomerId: 400235
MerchantId: 496
UserName: apitest
Password: api123

Test Kart:
- Kart No: 5188 9619 3919 2544
- CVV: 929
- Son Kullanma: 06/25
- 3D Şifre: 123456
```

## URL'ler

### Test Ortamı
- Kart Doğrulama: `https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelPayGate`
- Provizyon: `https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelProvisionGate`

### Production
- Kart Doğrulama: `https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate`
- Provizyon: `https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate`

## Log Kontrolü

İşlem sırasında log'ları kontrol edin:

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

Log'larda görecekleriniz:
- `Kuveytturk HashData Debug`: Hash hesaplama detayları
- `Kuveytturk XML Request`: Bankaya gönderilen XML
- `Kuveytturk Callback XML`: Bankadan dönen callback
- `Kuveytturk Provision XML Request/Response`: Provizyon isteği ve cevabı

## Önemli Notlar

1. **IP Adresi**: Artık otomatik olarak alınıyor, manuel tanımlama gerekmez
2. **HashData**: Doğru algoritma kullanılıyor, hata almamalısınız
3. **2 Aşamalı İşlem**:
   - Aşama 1: Kart doğrulama (3D Secure şifre girişi)
   - Aşama 2: Provizyon alma (ödeme çekimi)
4. **Callback URL**: `env('APP_URL') . "/api/payment/callback"` olarak ayarlandı
5. **User Bilgileri**: `$user->phone`, `$address->city`, `$address->address` gibi alanların dolu olduğundan emin olun

## Sorun Giderme

### "HashDataError" Hatası
✅ Düzeltildi! Artık doğru algoritma kullanılıyor.

### "IP adresi tanımlı değil" Hatası
✅ Düzeltildi! `ClientIP` otomatik olarak ekleniyor.

### Callback Gelmiyor
- `env('APP_URL')` değerinin doğru olduğundan emin olun
- Sunucunuzun dışarıdan erişilebilir olduğundan emin olun
- Test ortamında ngrok gibi araçlar kullanabilirsiniz

### Debug İçin
Log dosyasında tüm detaylar var:
```bash
tail -f storage/logs/laravel.log | grep Kuveytturk
```

## Destek

Sorun yaşarsanız:
- Log dosyalarını kontrol edin
- Kuveyt Türk destek: sanalposdestek@kuveytturk.com.tr
- Döküman: `kuveyt-turk-api-dokuman.txt`