İyzico ve PayTR ile Entegre Umbraco E-Ticaret Çözümleri

İyzico ve PayTR ile Entegre Umbraco E-Ticaret Çözümleri

Türkiye'de bir e-ticaret sitesi kuruyorsanız, ödeme altyapısı kararı işin bel kemiğidir. Uluslararası ödeme sağlayıcıları ne kadar güçlü olursa olsun, Türk tüketicinin alışkanlıkları, bankaların taksit yapıları ve yasal gereklilikler sizi her zaman yerel çözümlere yönlendirir. Iyzico ve PayTR, bu noktada öne çıkan iki isim. Umbraco ile bu iki sağlayıcıyı entegre etmek ise hem mümkün hem de doğru yapıldığında son derece verimli.

Bu yazıda gerçek bir proje deneyimine dayanarak Umbraco üzerinde Iyzico ve PayTR entegrasyonunun nasıl kurulduğunu, ne zaman hangisini tercih etmeniz gerektiğini ve süreçte karşılaşabileceğiniz teknik engelleri aktaracağım.

Umbraco Neden E-Ticaret için Tercih Ediliyor?

Umbraco, Türkiye'de kurumsal içerik yönetim sistemi (CMS) olarak giderek daha fazla tercih edilen bir .NET tabanlı platform. Özellikle kurumsal web sitelerinde güçlü bir geçmişi olan Umbraco, e-ticaret tarafında ise Umbraco Commerce (eski adıyla Vendr) modülüyle birlikte güçlü bir altyapı sunuyor.

Shopify veya WooCommerce gibi hazır platformların aksine Umbraco, geliştirici ekiplerine çok daha fazla kontrol tanıyor. Bu esneklik özellikle şu durumlarda kritik oluyor:

• Ödeme akışının tamamen özelleştirilmesi gerektiğinde
• Farklı müşteri segmentlerine (bireysel / kurumsal) ayrı fiyatlandırma mantığı uygulanacağında
• İçerik ve e-ticaret yönetiminin tek bir panel üzerinden yürütülmek istendiğinde

Iyzico Entegrasyonu: Adım Adım Yaklaşım

Iyzico Neden Öne Çıkıyor?

Iyzico, Türkiye'deki en yaygın kullanılan ödeme altyapılarından biri. Taksit seçenekleri, 3D Secure desteği, kolay sandbox ortamı ve iyi dokümante edilmiş API'si sayesinde geliştirici deneyimi oldukça düzgün. Özellikle son tüketiciye (B2C) yönelik projelerde sıkça tercih edilen bu yapı, Umbraco Commerce ile birlikte çalışacak şekilde oldukça temiz kurgulanabiliyor.

Teknik Entegrasyon Nasıl Kurgulanır?

Umbraco Commerce, Payment Provider arayüzü üzerinden özel ödeme sağlayıcıları tanımlamanıza olanak tanır. Iyzico entegrasyonu için temel akış şu şekilde işliyor:

1. NuGet paketi veya özel provider sınıfı

Iyzico'nun resmi .NET SDK'sı (Iyzipay) NuGet üzerinden projeye dahil edilir. Ardından PaymentProviderBase<IyzicoSettings> sınıfından türeyen bir provider yazılır.

public class IyzicoPaymentProvider : PaymentProviderBase<IyzicoSettings>
{
    public override async Task<PaymentFormResult> GenerateFormAsync(
        PaymentProviderContext<IyzicoSettings> ctx, CancellationToken cancellationToken)
    {
        var options = new Options
        {
            ApiKey = ctx.Settings.ApiKey,
            SecretKey = ctx.Settings.SecretKey,
            BaseUrl = ctx.Settings.SandboxMode 
                ? "https://sandbox-api.iyzipay.com" 
                : "https://api.iyzipay.com"
        };
        // Sepet ve müşteri bilgilerini Iyzico modellerine map et
        // ...
    }
}

2. Sipariş bilgilerinin haritalanması

Umbraco Commerce'teki Order nesnesindeki ürün satırları, Iyzico'nun beklediği BasketItem listesine dönüştürülür. Burada dikkat edilmesi gereken en kritik nokta: Iyzico'nun fiyat doğrulaması. Sepetteki toplam ile gönderilen fiyat tutarsızsa işlem reddedilir.

3. Callback ve webhook yönetimi

Ödeme tamamlandığında Iyzico, tanımladığınız callback URL'e POST atar. Bu endpoint, Umbraco'da bir controller ile karşılanır ve sipariş durumu güncellenir. Sandbox ortamında bu akışı ngrok gibi bir araçla kolayca test edebilirsiniz.

Sık Karşılaşılan Sorunlar

• Fiyat uyumsuzluğu hataları: Umbraco Commerce vergisiz fiyatla çalışırken Iyzico'ya vergili toplam gönderilmesi gerekiyor. Vergi hesaplama katmanına dikkat edin.
• Karakter kodlama: Türkçe karakter içeren adres veya müşteri bilgileri zaman zaman imza doğrulama hatalarına yol açabiliyor. Gönderim öncesinde string normalize etmek faydalı.

PayTR Entegrasyonu: Iframe mi, API mi?

PayTR'nin Güçlü Yönleri

PayTR, özellikle KOBİ segmentinde geniş bir kullanıcı tabanına sahip. Komisyon oranları konusunda esneklik sunması, hızlı onay süreci ve özellikle link ile iframe tabanlı ödeme akışındaki basitliği öne çıkmasını sağlıyor. Büyük ölçekli kurumsal projelerde Iyzico daha çok tercih edilse de PayTR, hızlı devreye alınması gereken projelerde son derece pratik.

Iframe Yöntemi ile Entegrasyon

PayTR'nin Umbraco'ya entegrasyonunda en yaygın yaklaşım iframe tabanlı ödeme sayfasıdır. Token alımı ve iframe render akışı şu şekilde işler:

// Token isteği için gerekli alanlar hazırlanır
var postData = new Dictionary<string, string>
{
    { "merchant_id", settings.MerchantId },
    { "user_ip", httpContext.Connection.RemoteIpAddress?.ToString() },
    { "merchant_oid", order.OrderNumber },
    { "email", order.CustomerInfo.Email },
    { "payment_amount", (order.TotalPrice.Value.WithTax * 100).ToString("F0") },
    { "token", ComputePayTRToken(settings, order) },
    // Diğer alanlar...
};

Token başarıyla alındıktan sonra, frontend tarafında PayTR'nin iframe'i sayfaya yüklenir ve ödeme akışı tamamen PayTR'nin güvenli ortamında tamamlanır.

İpn (Instant Payment Notification) Yönetimi

PayTR, ödeme sonucunu sizin belirlediğiniz IPN URL'e gönderir. Bu endpoint'te token doğrulaması yapılır ve sipariş statüsü güncellenir. Dikkat: IPN endpoint'i [ValidateAntiForgeryToken] gibi middleware'lerden muaf tutulmalı, aksi takdirde PayTR'nin POST isteği reddedilir.

Iyzico mu, PayTR mi? Karar Kriterleri

Her iki sağlayıcıyı farklı projelerde kullandıktan sonra şu çerçeveye ulaştım:

Eğer uzun vadeli, ölçeklenebilir bir B2C ürünü geliştiriyorsanız Iyzico altyapısına yatırım yapın. Hızlı devreye almak istediğiniz bir MVP veya KOBİ projesi söz konusuysa PayTR'nin pratikliği işinizi görür.

Umbraco Commerce'e Özel Dikkat Edilmesi Gereken Noktalar

Ödeme entegrasyonlarını Umbraco Commerce ile yaparken genel .NET projelerinden farklı bazı durumlarla karşılaşırsınız:

Order lifecycle yönetimi: Umbraco Commerce'te bir sipariş "finalised" statüsüne geçmeden ödeme tamamlanmış sayılmaz. Provider'ınız doğru statü geçişlerini tetiklemezse stok düşürmeme, e-posta göndermeme gibi problemler yaşarsınız.

Currency ve tax zone yapısı: Türkiye için KDV yapılandırması ayrıca tanımlanmalı. Ödeme sağlayıcısına gönderilecek tutar bu yapıdan türetildiği için yanlış kurgulanan bir vergi bölgesi tüm fiyat hesaplamalarını bozar.

Store context: Birden fazla mağaza (store) kullanan Umbraco Commerce kurulumlarında her mağazanın ayrı payment provider ayarlarına ihtiyacı olabilir. Bu senaryoda StoreId bazlı konfigürasyon ayrımı yapmak gerekir.

Sonuç

Umbraco üzerinde Iyzico veya PayTR entegrasyonu teknik olarak güçlü ve esnek çözümler sunar; ancak sürecin sorunsuz ilerlemesi için hem ödeme sistemlerinin API mantığını hem de Umbraco Commerce altyapısını doğru şekilde kurgulamak gerekir. Umbraco Türkiye olarak, projelerinizde ihtiyaçlarınıza en uygun ödeme altyapısını belirliyor, entegrasyon süreçlerini uçtan uca yönetiyor ve performans, güvenlik ile kullanıcı deneyimini birlikte optimize ediyoruz. Eğer siz de Umbraco tabanlı e-ticaret projenizde doğru ödeme çözümünü hayata geçirmek istiyorsanız, uzman ekibimizle size özel çözümler sunabiliriz.