Magento 2 Özel Ödeme Ağ Geçidi (Payment Gateway) Geliştirme ve 3D Secure Mimarisi

1. Problem: Kırılgan Üçüncü Parti POS Eklentileri, 3DS Kopmaları ve Çift Tahsilat Riski

Türkiye'de e-ticaret ve B2B işletmeleri tek bir ödeme sağlayıcısıyla yetinmeyip banka sanal POS'ları, İyzico, PayTR, Param veya B2B kapalı devre kredi/tahsilat çözümlerini aynı checkout içinde çalıştırmak ister. Piyasadaki amatör ödeme eklentileri kullanıldığında ise en kritik gelir noktasında şu hatalar yaşanır:

1. 3D Secure Oturum Kopması: Banka 3DS doğrulamasından siteye dönüldüğünde SameSite çerez politikaları nedeniyle müşteri oturumunun kaybolması ve sepetin boşalması.
2. Callback Race Condition (Yarış Durumu): Hem kullanıcının tarayıcı dönüşü hem de ödeme sağlayıcısının arka plan webhook'u (IPN) aynı milisaniyede ulaştığında siparişin iki kez onaylanması veya faturalanması.
3. Taksit ve Vade Farkı Uyuşmazlığı: Banka BIN sorgusuna göre oluşan taksit komisyonunun Magento sipariş toplamlarına (Quote / Order total) doğru işlenmemesi yüzünden muhasebe mutabakatının bozulması.
4. Güvenlik Riskleri: Banka yanıtındaki HMAC/SHA imza doğrulamasının atlanması veya hata loglarına yanlışlıkla kart/token verisi basılması.

2. Mimari Yaklaşım: Magento 2 Payment Provider Gateway Katmanları

Güncel Magento 2 ödeme mimarisi, ödeme iş mantığını bağımlılık enjeksiyonu (di.xml) üzerinden izole parçalara böler. Böylece bir banka API'sinde yapılacak değişiklik tüm sepet/checkout akışını etkilemez.

A. Çekirdek Modül Dosya Yapısı (YilmazSoft_CustomGateway)

app/code/YilmazSoft/CustomGateway/
├── etc/
│   ├── module.xml
│   ├── config.xml
│   ├── payment.xml
│   └── di.xml
├── Gateway/
│   ├── Config/Config.php
│   ├── Http/Client/PaymentClient.php
│   ├── Request/AuthorizeRequestBuilder.php
│   ├── Response/AuthorizeResponseHandler.php
│   └── Validator/SignatureValidator.php
├── Controller/
│   ├── ThreeDS/Start.php
│   └── ThreeDS/Callback.php
└── view/frontend/web/js/view/payment/method-renderer/custom-gateway.js

B. payment.xml ve di.xml Üzerinden Komut Havuzu (Command Pool)

Ödeme yöntemi doğrudan sınıf kalıtımı yerine sanal tip (virtualType) tanımlarıyla yapılandırılır:

<!-- app/code/YilmazSoft/CustomGateway/etc/di.xml (özet mimari) -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="YilmazSoftCustomGatewayFacade" type="Magento\Payment\Model\Method\Adapter">
        <arguments>
            <argument name="code" xsi:type="string">yilmazsoft_gateway</argument>
            <argument name="formBlockType" xsi:type="string">Magento\Payment\Block\Form</argument>
            <argument name="infoBlockType" xsi:type="string">Magento\Payment\Block\Info</argument>
            <argument name="valueHandlerPool" xsi:type="object">YilmazSoftGatewayValueHandlerPool</argument>
            <argument name="commandPool" xsi:type="object">YilmazSoftGatewayCommandPool</argument>
        </arguments>
    </virtualType>
</config>

Bu yapıda CommandPool içinde authorize, capture, void ve refund komutları birbirinden tamamen ayrılır; her komut kendi Request Builder (veriyi hazırlar), Client (TLS 1.2+ ile sağlayıcıya iletir), Validator (dönen yanıtın tutar ve imzasını doğrular) ve Handler (sipariş statüsünü günceller) zincirini çalıştırır.

C. 3D Secure Dönüşü, İmza Doğrulama ve Idempotency Kilidi

Türkiye'deki bankacılık düzenlemeleri nedeniyle bireysel kart işlemlerinin büyük bölümünde 3D Secure zorunludur. Güvenli dönüş akışı şu dört kurala dayanmalıdır:

1. CSRF Muafiyeti + Sıkı İmza Kontrolü: Bankadan POST ile dönen Callback controller'ı CsrfAwareActionInterface uygular; buna karşılık gelen isteği mutlaka ödeme sağlayıcısının gizli anahtarıyla (HMAC-SHA256 / SHA-512) hesaplanan imza ve tutar eşitliği üzerinden doğrular. İmza tutmazsa işlem derhal reddedilir (403).
2. Idempotent Durum Geçişi: Aynı transaction_id veya order_increment_id için hem müşteri yönlendirmesi hem sunucu-sunucu webhook geldiğinde, yalnızca ilk doğrulanan istek siparişi processing durumuna geçirir ve faturayı keser; ikinci istek mevcut sonucu sessizce onaylar.
3. Bekleyen Siparişlerin Otomatik Temizliği: Müşteri 3DS ekranını kapatıp çıkarsa pending_payment durumunda kalan siparişler için zamanlanmış cron görevi belirli bir dakika sonunda siparişi iptal edip MSI stok rezervini geri bırakır.
4. PCI-DSS Veri Hijyeni: Kart verisi (PAN, CVV) hiçbir koşulda Magento veritabanına veya var/log/ dosyalarına yazılmaz; ödeme formu mümkünse sağlayıcının Hosted / iFrame SDK'sı üzerinden çalıştırılır ve loglarda yalnızca maskelenmiş son 4 hane tutulur.

Ödeme ve ERP verilerinin uçtan uca bağlanması hakkında daha fazla detay için API Entegrasyonu Rehberi ve Magento 2 Özel Mimari Rehberi yazılarımızı okuyabilirsiniz.

3. Süre ve Bütçe Aralığı (2026)

4. Sık Sorulan Sorular

Magento 2'de neden eski AbstractMethod yerine Payment Provider Gateway mimarisi kullanılmalıdır?

Eski AbstractMethod sınıfı Magento çekirdeğinde kullanımdan kaldırılmıştır (deprecated). Güncel Payment Provider Gateway mimarisi; di.xml üzerinden CommandPool, RequestBuilder, HttpClient, Validator ve ResponseHandler sınıflarını ayrıştırarak daha test edilebilir, güvenli ve yükseltmeye dayanıklı bir ödeme akışı sağlar.

3D Secure dönüşünde müşterinin oturumu düşerse veya aynı callback iki kez gelirse sipariş nasıl korunur?

Callback controller tek kullanımlık imzalı bir payment_token ve HMAC/hash doğrulamasıyla çalışmalı, veritabanı seviyesinde atomik kilit (idempotency check) uygulayarak aynı işlem numarasının iki kez sipariş onaylamasını veya tahsilat kaydı açmasını önlemelidir.

Özel ödeme modülü geliştirirken PCI-DSS uyumluluğu nasıl sağlanır?

Kart numarası (PAN) ve CVV verileri kesinlikle sunucu loglarına, veritabanına veya session dosyalarına yazılmamalıdır. Mümkün olan her senaryoda ödeme sağlayıcısının iFrame/Hosted form akışı tercih edilmeli; doğrudan API kullanılıyorsa yalnızca tokenize edilmiş referanslar saklanmalıdır.

Özel ödeme geçidi veya B2B/E-Ticaret ödeme altyapısı geliştirme bütçesi nedir?

Tekil Sanal POS & Ödeme Entegrasyonu ₺24.900 – ₺54.900 aralığından başlar. Ödeme modülü dahil uçtan uca e-ticaret altyapısı Basic ₺49.900 / Pro ₺82.900, çoklu banka POS ve B2B cari tahsilat sistemleri ₺54.900 – ₺129.000 (B2B Bayi Portalı ₺74.900 – ₺164.000), kurumsal Enterprise Magento 2 mimarileri ise ₺139.900+ bütçe aralığındadır.

5. Sonraki Adım: Güvenli ve Kesintisiz Ödeme Altyapısı Kurun

İlgili hizmetlerimiz ve rehberlerimiz:

• E-Ticaret Sitesi Yaptırma
• Özel Yazılım ve API Entegrasyonu
• Magento 2 Özel Mimari ve Modül Geliştirme
• Magento 2 ERP ve Muhasebe Entegrasyon Rehberi
• Proje Fiyat Hesaplama

Özel ödeme geçidi veya e-ticaret tahsilat mimarisi için teknik görüşme planlayın:

• Telefon & WhatsApp: 0543 256 97 07
• E-posta: [email protected]
• İletişim: Ödeme Entegrasyonu Teklifi Al