Iyzico ve PayTR 3D Secure Ödeme Akışı Next.js ve Laravel ile Nasıl Kodlanır?

1. Giriş ve Karşılaşılan Temel Zorluklar

Kullanıcı kart bilgilerini girdikten sonra banka SMS doğrulama ekranına (3D Secure) yönlendirme ve dönen ödeme sonucunu (Success/Fail) sunucu tarafında doğrulamak karmaşık bir durum (state) yönetimi gerektirir.

Modern kurumsal yazılım mimarisinde bu adımı doğru tasarlamak; hem uygulamanın bakım maliyetini (maintainability) düşürür hem de gelecekteki ölçekleme (scaling) süreçlerinde refactor ihtiyacını en aza indirir. Bu rehberde, sektörde kabul görmüş standartlar ışığında adım adım uygulamayı ele alıyoruz.

2. Ortam Hazırlığı ve Gerekli Bağımlılıklar

Geliştirmeye başlamadan önce sistem ortamınızın ve ilgili paketlerin hazır olduğundan emin olmalısınız. Terminalinizde aşağıdaki komutları çalıştırarak ilgili yapılandırmayı tamamlayın:

• Adım: Iyzico veya PayTR API anahtarlarını (.env) ortamına ekleyin.
• Adım: Sepet tutarı, müşteri bilgileri ve sepet kalemlerini hazırlayan ödeme başlatma servisini kurun.

3. Uygulama Mimarisi ve Kod Örneği

Aşağıdaki kod bloğunda, temiz kod (Clean Code) prensiplerine ve SOLID standartlarına uygun olarak tasarlanmış örnek implementasyonu inceleyebilirsiniz:

<?php

namespace App\Services;

use Iyzipay\Options;
use Iyzipay\Model\ThreedsInitialize;
use Iyzipay\Request\CreatePaymentRequest;

class IyzicoPaymentService
{
    public function initialize3D(array $orderData, string $callbackUrl): string
    {
        $options = new Options();
        $options->setApiKey(config('services.iyzico.api_key'));
        $options->setSecretKey(config('services.iyzico.secret_key'));
        $options->setBaseUrl(config('services.iyzico.base_url'));

        $request = new CreatePaymentRequest();
        $request->setLocale('tr');
        $request->setConversationId($orderData['order_code']);
        $request->setPrice($orderData['amount']);
        $request->setPaidPrice($orderData['amount']);
        $request->setCurrency('TRY');
        $request->setCallbackUrl($callbackUrl);

        // 3D Secure HTML içeriğini al
        $threedsInitialize = ThreedsInitialize::create($request, $options);

        if ($threedsInitialize->getStatus() !== 'success') {
            throw new \Exception($threedsInitialize->getErrorMessage());
        }

        // Banka ekranını açacak HTML formu
        return $threedsInitialize->getHtmlContent();
    }
}

4. Kod Analizi ve Çalışma Mantığı

Bu servis Iyzico sunucularına sepet ve tutar detaylarını iletir. Başarılı yanıtta bankanın 3D Secure SMS ekranına yönlendiren HTML form içeriği döner. Kullanıcı onay verdiğinde Iyzico callback URL'ine POST isteği atar.

Yukarıdaki implementasyonda dikkat edilmesi gereken en kritik husus, işlemlerin bağımsız (decoupled) ve test edilebilir şekilde katmanlara ayrılmış olmasıdır. Bu yaklaşım, birim testlerin (Unit Tests) ve entegrasyon testlerinin hızlıca yazılabilmesine olanak tanır.

5. Performans ve Güvenlik İpuçları

Canlı üretim (production) ortamında sistemin kararlı çalışması için aşağıdaki pratikleri mutlaka dikkate almalısınız:

• Callback URL'ine gelen ödeme sonucunu yalnızca frontend'e güvenerek onaylamayın; sunucudan 'ThreedsPayment::create' ile son kez teyit edin.
• Ödeme işlemi öncesinde sipariş durumunu 'pending_payment' olarak işaretleyin; mükerrer ödemeleri engellemek için idempotent anahtar (order_code) kullanın.
• Stok düşümünü sadece ödeme banka tarafından onaylandıktan sonra veritabanı transaction'ı içinde gerçekleştirin.

6. En Sık Yapılan Hatalar ve Hata Ayıklama (Troubleshooting)

Kullanıcı banka SMS ekranında sayfayı kapattığında sepetin havada kalmaması için zaman aşımı (timeout) mekanizması kurmayı unutmamalısınız.

Eğer beklenmedik bir hata ile karşılaşırsanız; öncelikle log dosyalarını incelemeli, ortam değişkenlerinin (.env) doğru tanımlandığını doğrulamalı ve önbellek (cache) mekanizmalarını temizleyerek sistemi yeniden başlatmalısınız.

7. Sonuç ve Mimari Değerlendirme

3D Secure ödeme altyapısı, e-ticaret sitelerinde çalıntı kart dolandırıcılığı (chargeback) riskini sıfıra indiren yasal zorunluluktur.

Cengiz Bozdemir olarak 18 yılı aşkın kurumsal yazılım mimarlığı deneyimimle tavsiyem; sistem tasarımında her zaman sürdürülebilirlik, güvenlik ve yüksek eşzamanlılık (high concurrency) hedeflerini ön planda tutmanızdır. Kurumsal projelerinizde özel mimari danışmanlık veya uçtan uca yazılım geliştirme desteği için bizimle iletişime geçebilirsiniz.