CS-Cart iyzico Sanal POS Entegrasyonu

Online satışta müşterinin sepeti doldurduğu an ile ödemeyi tamamladığı an arasındaki mesafe, mağazanızın gelirini doğrudan belirler. Kart bilgisi girmeye çalışan bir müşteri; güvensiz görünen bir form, çalışmayan bir taksit seçeneği ya da ödeme sonrası “siparişim alındı mı?” belirsizliğiyle karşılaştığında sepeti terk eder. SoftCrafter iyzico eklentisi, CS-Cart mağazanızda bu mesafeyi kısaltmak ve ödemeyi güvenli, izlenebilir ve yönetilebilir hale getirmek için geliştirildi.

Eklenti, kartlı ödemeyi iyzico’nun barındırdığı Checkout Form akışıyla alır. Müşteri iyzico’nun formuna yönlendirilir, ödemesini yapar ve mağazanıza döner. Kart numarası, son kullanma tarihi ve güvenlik kodu hiçbir aşamada sizin sunucunuza, veritabanınıza ya da yedeklerinize ulaşmaz. Bu, hem müşteri güveni hem de sizin üzerinizdeki güvenlik ve uyum yükü açısından büyük bir avantajdır.

Neden Checkout Form ile entegrasyon?

Kartlı ödeme entegrasyonunda iki temel yol vardır: kart alanlarını kendi sayfanızda çizmek ya da ödeme kuruluşunun barındırdığı sayfaya yönlendirmek. Kendi sayfanızda çizdiğiniz kart alanları, kart verisinin sizin ortamınızdan geçmesi demektir; bu da güvenlik denetimlerini, sızıntı riskini ve kart sektörü uyum süreçlerinin kapsamını büyütür. Barındırılan form yaklaşımında ise kart verisi doğrudan ödeme kuruluşunun altyapısında kalır.

PCI güvenlik standartları konseyinin açıkladığı çerçevede de ödeme sayfasına yönlendirme yapan, kart verisini kendi sistemlerinde işlemeyen ticari siteler, sorumluluk kapsamı bakımından daha dar bir alanda kalır. Bu yüzden iyzico Checkout Form yaklaşımı, özellikle küçük ve orta ölçekli mağazalar için hem pratik hem de güvenli bir tercihtir. Yine de uyum yükümlülüğünüzün kesin kapsamını ödeme kuruluşunuzla ve güvenlik danışmanınızla teyit etmenizi öneririz.

Ödeme doğrulaması: sipariş ne zaman “ödendi” olur?

Ödeme entegrasyonlarında en kritik soru şudur: Müşteri ödemeyi yaptığında siparişin ödendi sayılmasına hangi bilgi karar verir? Birçok basit entegrasyon, müşterinin tarayıcısının mağazaya döndüğü sayfaya bakarak siparişi onaylar. Oysa bu sayfa müşterinin tarayıcısı tarafından kapatılabilir, taklit edilebilir ya da hiç yüklenmeyebilir.

SoftCrafter iyzico eklentisi bu yaklaşımı kullanmaz. Sipariş yalnızca iyzico tarafı doğrulandığında ödenmiş olur. Doğrulama dört koşula dayanır:

• iyzico’da ilgili ödeme kaydının bulunması,
• iyzico’nun gönderdiği V3 imzalı bildirimin doğrulanması,
• tutarın kuruşu kuruşuna eşleşmesi,
• girişim, sipariş ve üye işyeri bilgilerinin birbirini tutması.

Bu dört koşuldan biri sağlanmazsa sipariş ödendi olarak işaretlenmez ve durum inceleme listesine düşer. Müşteri ödedi ama bildirim gelmedi gibi uç durumlar için ayrı bir kurtarma mekanizması da vardır; bu konuya aşağıda değineceğiz.

Taksit ve 3D Secure

Türkiye’de online alışverişte taksit seçeneği, dönüşüm oranını doğrudan etkileyen unsurlardan biridir. Eklentinin ayarlarında etkin taksit sayıları tanımlanır; bu sayılar iyzico formunda müşteriye sunulur. Hangi taksit seçeneklerinin hangi kartlarda geçerli olacağı iyzico ve bankalar tarafından belirlenir; siz mağaza tarafında hangi taksit sayılarının sunulacağını kontrol edersiniz.

3D Secure doğrulaması, banka adımıdır ve iyzico’nun barındırdığı çerçevenin içinde çalışır. Eklentinin içerik güvenliği kuralları, sağlayıcının yönlendirmesine izin verirken üst pencerenin ele geçirilmesini engelleyecek şekilde yapılandırılmıştır. Başarısız bir 3D Secure bildirimi de eklenti tarafından kurtarılır; yani teknik bir aksaklık yüzünden ödemesi yarım kalan müşteri sipariş kaydı olmadan ortada kalmaz.

Ödeme başarısız olduğunda müşteri sepeti bozulmadan ödeme adımına geri döner. Bu küçük gibi görünen ayrıntı, “şifreyi yanlış girdim, sepetim gitti” deneyimini önleyerek gerçek bir satış kaybını engeller.

Sandbox ve canlı ortam: güvenli geçiş

Her ödeme yöntemi sandbox ya da canlı modda çalışabilir ve ikisi aynı mağazada yan yana durabilir. Bu sayede canlı ödeme yöntemi müşterilere açıkken, test için ayrı bir sandbox yöntemi oluşturup yeni ayarları denemeniz mümkündür.

Canlıya geçiş adımları nettir:

1. Sandbox’ta test: Sandbox anahtarlarıyla test siparişi verin, iyzico formunda ödeyin. Sipariş ödenmiş görünmeli ve siparişteki ödeme adımları sekmesi başlatma, doğrulama ve sonlandırma adımlarını göstermelidir.
2. Canlı bilgileri girin: Üye işyeri numarası, API anahtarı ve güvenlik anahtarını girin, ortamı canlı yapın.
3. Gerçek ödeme deneyin: iyzico canlıya geçişten önce birkaç liralık gerçek bir ödeme ister. Aynı gün iade edilirse ekstreye yansımaz.
4. Yöntemi etkinleştirin: Yöntemin durumu etkin olduğunda müşteriler iyzico seçeneğini görmeye başlar.

API ve güvenlik anahtarları mağazanızın şifreleme anahtarıyla (crypt_key) şifrelenir ve yönetim arayüzünde maskelenir. Kaydederken alanı boş bırakırsanız mevcut değer korunur.

İade ve iptal: iki adımlı, güvenli akış

Para iadesi, hata payının en yüksek olduğu operasyonlardan biridir. Yanlış tutarda iade, iki kez iade ya da yanıtı okunamayan bir isteğin tekrarı doğrudan para kaybıdır. Bu yüzden eklenti iadeyi iki adımlı yürütür: önce sunucu tarafında hazırlık, ardından ayrı bir onay. Her iki adım için de özel yetki gerekir; böylece iade işlemini yalnızca sorumlu kişiler yapabilir.

• Tam iptal: Aynı gün içindeki tam geri alma iyzico’ya iptal olarak gönderilir; gerekirse iyzico bunu iadeye çevirir.
• Kısmi iade: Kalan iade edilebilir bakiye, istenen tutardan değil iyzico’nun onayladığı tutardan hesaplanır.
• Sipariş durumları: “İade edildi” ve “Kısmen iade edildi” durumları oluşturulur; hangi sipariş durumunun kullanılacağını siz seçersiniz.
• Okunamayan yanıt: Sonucu okunamayan bir iade, tutarı rezerve ederek “bilinmiyor” durumunda bekler ve otomatik tekrar edilmez. Tekrar gönderim çift iadeye yol açabileceğinden bu işlemler iyzico’ya sorularak çözülür.

İadenin ödemenin geldiği hesaba döndüğünü ve ödeme başına yapıldığını, satıcı başına yapılmadığını belirtmek gerekir.

Operasyon araçları: ödeme sorunlarını görünür kılmak

Ödeme sistemleri “çalıştığı sürece” görünmez, bozulduğunda ise her dakika para kaybettirir. Eklentinin operasyon araçları, sorunları siz fark etmeden önce görünür kılmak için tasarlandı:

• Ödeme adımları sekmesi: Her siparişte girişim, başlatma, doğrulama, sonlandırma ve geri alma adımlarını sırasıyla gösterir. Ham yanıt, jeton ya da anahtar gösterilmez.
• iyzico sağlık ekranı: Ödeme yönteminin varlığını, kimlik bilgilerinin eksiksizliğini ve son iletişimi tek bakışta gösterir.
• Çözülmemiş işler: Yarıda kalan girişimleri, okunamayan iadeleri ve uyumsuz kayıtları listeler.
• Terk edilen girişimleri kapatma: 30 dakikadan eski, cevapsız girişimler iki adımla kapatılabilir; bu yalnızca iş kalemini kapatır, ödemeyi başarısız işaretlemez.
• Komut satırı kurtarma: Gözden geçirme, mutabakat ve kanıt komutları varsayılan olarak “kuru çalıştırma” modundadır; gerçek işlem için açıkça onay gerekir.

Bu araçlar, “müşteri ödedi ama sipariş ödenmemiş görünüyor” gibi destek taleplerini dakikalar içinde çözülebilir hale getirir.

Hangi mağazalar için uygun?

iyzico eklentisi, Türk Lirası ile satış yapan ve kartlı ödemeyi güvenli, hızlı ve izlenebilir şekilde almak isteyen her CS-Cart mağazası için uygundur. Özellikle şu durumlarda tercih edilir:

• Yeni açılan mağazalar: Kart verisini kendi sisteminizde tutmak istemiyor, güvenlik ve uyum yükünü sade tutmak istiyorsanız barındırılan form en kısa yoldur.
• Taksit odaklı satış yapanlar: Yüksek sepet tutarlı ürünlerde (elektronik, mobilya, ev aletleri, moda) taksit seçeneği satışın ayrılmaz parçasıdır.
• Operasyon ekibi küçük olanlar: Ödeme adımları sekmesi ve sağlık ekranı, teknik ekibi olmayan işletmelerin de ödeme sorunlarını yönetebilmesini sağlar.
• Çok kanallı satış yapanlar: Aynı CS-Cart altyapısında hem web mağazası hem de mobil uygulama üzerinden satış yapıyorsanız ödeme akışı tek yerde toplanır.

Birden fazla ödeme kuruluşuyla çalışmak isterseniz aynı mağazada farklı ödeme yöntemleri yan yana tanımlanabilir; müşteriye hangisinin sunulacağını yönetim panelinden siz belirlersiniz.

Taksit stratejisi nasıl kurulur?

Taksit sayılarını belirlerken yalnızca “ne kadar çok o kadar iyi” mantığıyla hareket etmemek gerekir. Taksit sayısı arttıkça müşteri için aylık yük azalır ancak ödeme kuruluşu ve bankalar tarafından uygulanan koşullar işletmenizin maliyetini etkileyebilir. Bu nedenle önerimiz şudur: önce hangi ürün gruplarında taksit talebinin yoğun olduğunu inceleyin, ardından ödeme kuruluşunuzla anlaştığınız koşullara göre mağazada sunulacak taksit sayılarını belirleyin. Eklentide bu sayıları değiştirmek, kod yazmadan ayar ekranından yapılır.

Canlıya geçiş kontrol listesi

Ödeme entegrasyonunu canlıya almadan önce şu maddeleri tek tek işaretlemenizi öneririz:

1. Mağazanın ana para birimi Türk Lirası olarak ayarlı mı?
2. Vitrin HTTPS üzerinden çalışıyor mu ve sertifika geçerli mi?
3. iyzico API adresine sunucudan HTTPS çıkışı açık mı?
4. Bildirim (webhook) adresi dışarıdan HTTPS ile erişilebilir mi; güvenlik duvarı ve önbellek katmanı bu isteği engelliyor mu?
5. İade ve mutabakat yetkileri yalnızca sorumlu yönetici gruplarına mı verildi?
6. Sandbox’ta başarılı ödeme, başarısız ödeme ve iade senaryoları denendi mi?
7. Canlı anahtarlarla küçük tutarlı gerçek bir ödeme yapılıp iade edildi mi?
8. Veritabanı ve dosya yedekleri güncel mi?

Bu liste, ödeme sorunlarının büyük çoğunluğunu müşteri karşısına çıkmadan yakalamanızı sağlar.

Güvenlik yaklaşımı

• Kart numarası, son kullanma tarihi ve CVV mağazaya hiç ulaşmaz.
• Günlükler ve ekranlar yalnızca güvenli referanslar ve sınırlı gerekçeler içerir.
• Gelen istekler boyut, alan sayısı ve derinlik sınırlarıyla okunur.
• API istekleri iyzico’nun imzalı yetkilendirme başlığıyla gönderilir.
• Ödeme, girişim ve denetim tabloları, eklenti devre dışı bırakılsa ya da kaldırılsa bile silinmez; böylece mali kayıtlar korunur.

Kurulum ve gereksinimler

Eklenti, CS-Cart ve Multi-Vendor için ayrı paketler halinde gelir (tek mağaza ve Multi-Vendor). CS-Cart paketin bildirdiği sürümü kendi sürümüyle karşılaştırır, eşleşmeyen paketi kurmayı reddeder.

Kurulum sırası: paketi yükleyin, eklentiyi kurup etkinleştirin, iki yetkiyi (iade ve mutabakat) ilgili yönetici grubuna verin, iyzico Checkout Form işlemcisiyle ödeme yöntemi oluşturun ve kimlik bilgilerini girin. Yükseltmelerde CS-Cart’ın “dosyaları değiştir” seçeneği kullanılır; ardından göç komutu eksik tablo ve yetkileri tamamlar. Bu adımların tamamını biz yaparız; siz yalnızca iyzico hesap bilgilerinizi paylaşırsınız.

Pazaryeri (Multi-Vendor) projeleri için not

Multi-Vendor için ayrı paket mevcuttur ve eklenti pazaryeri mağazalarında kartlı ödeme alır. Bilmeniz gereken bir sınır vardır: tahsilat tek hesaba geçer ve satıcı kırılımı sizin mağazanızda siparişin altında kayıt altında tutulur; iyzico tarafına satıcı bazlı alt üye işyeri bölüşümü gönderilmez. Satıcı ödemeleri mağazanızın kendi hak ediş sürecinde yönetilir. Pazaryeri modelinizde ödemenin satıcılara nasıl dağıtılacağı hukuki ve operasyonel bir karardır; ön görüşmede iş modelinizi dinleyip size uygun yapıyı birlikte netleştirebiliriz.

Bilinen sınırlar

Güvenilir bir entegrasyon, neyi yapmadığını da açıkça söyler:

• Yalnızca Türk Lirası desteklenir.
• Yalnızca barındırılan form vardır; kart alanları mağaza tarafından çizilmez.
• İade ödeme başına yapılır, satıcı başına değil.
• Alıcı kimlik numarası CS-Cart siparişinde bulunmadığı için iyzico’nun dokümante ettiği dolgu değeriyle gönderilir.

Sık karşılaşılan sorunlar ve çözümleri

• Eklenti kurulu ama menüde görünmüyor: İki yetki varsayılan olarak verilmemiştir; kullanıcı gruplarından verilmelidir.
• “Kimlik bilgileri reddedildi” hatası: Anahtarları karakter karakter kontrol edin; sandbox anahtarlarının yalnızca sandbox ortamında, canlı anahtarların canlı ortamda kullanıldığından emin olun.
• Müşteri ödedi, sipariş ödenmemiş görünüyor: Bildirim adresi HTTPS ile erişilebilir olmalı ve güvenlik duvarı ya da önbellek katmanı bu isteği engellememelidir. Çözülmemiş işler listesinden onarım yapılabilir.
• Ayar ekranında eksik yapı uyarısı: Veritabanı kullanıcısının tablo değiştirme yetkisi eksik olabilir; yetki verilip ekran yeniden açıldığında eklenti göçü tamamlar.

Teklif ve ön görüşme

Ödeme entegrasyonu, “bir eklenti kurdum, bitti” denecek bir iş değildir; test, canlıya geçiş, iade akışı, bildirim erişimi ve operasyon ekibinin eğitimi birlikte düşünülmelidir. SoftCrafter olarak CS-Cart’ın resmi partneri sıfatıyla lisanstan kuruluma, ödeme yönteminin canlıya alınmasından yayın sonrası bakıma kadar tüm süreci tek ekipte yürütürüz.

Kurulum ve entegrasyon çalışması projenize göre kalem kalem tekliflendirilir; teklifiniz ön görüşmeden sonra 1 iş günü içinde hazır olur. Formu bıraktığınızda ekibimiz sizi 15 dakika içinde arar. Başka bir ödeme kuruluşu da düşünüyorsanız PayTR Sanal POS eklentimize ve genel sanal POS entegrasyonu sayfasına da göz atabilirsiniz. Eklentinin ayrıntılı Türkçe dokümantasyonuna docs.softcrafter.dev adresinden ulaşabilirsiniz.