CS-Cart PayTR Sanal POS Entegrasyonu

Kartlı ödeme, bir e-ticaret mağazasının en hassas altyapı parçasıdır. Müşteri açısından güven, hız ve netlik; işletme açısından ise doğru tahsilat, izlenebilir iade ve kolay mutabakat demektir. SoftCrafter PayTR eklentisi, CS-Cart mağazanıza PayTR’nin iFrame V2 altyapısıyla kartlı ödeme ekler ve ödeme akışının her adımını kayıt altına alan, sorunları görünür kılan bir finans katmanıyla birlikte gelir.

Müşteri kartını PayTR’nin barındırdığı formda girer; kart verisi mağazanıza hiçbir aşamada ulaşmaz. Siparişin ödendi sayılması müşterinin tarayıcısına değil, PayTR’nin sunucudan sunucuya gönderdiği imzalı bildirime bağlıdır. Bu tasarım tercihi, “ödeme alındı mı?” sorusunun cevabını tahmine değil kanıta dayandırır.

PayTR iFrame V2 nasıl çalışır?

Müşteri ödeme adımında PayTR’yi seçtiğinde eklenti şu sırayı izler:

1. Siparişe bağlı bir ödeme girişimi kaydı açılır.
2. Eklenti PayTR’den bir ödeme jetonu ister; jeton 30 dakika geçerlidir.
3. PayTR’nin iFrame V2 formu mağaza sayfasında gösterilir.
4. Müşteri kart bilgilerini ve gerekirse banka doğrulamasını PayTR’nin ortamında tamamlar.
5. PayTR, sonucu mağazanın bildirim adresine imzalı olarak gönderir.
6. Eklenti imzayı doğrular, girişimi kilitler, tutarı karşılaştırır ve sonucu kaydeder.

Müşterinin geri döndüğü sayfa yalnızca bilgilendiricidir; ödemeyi hiçbir zaman onaylamaz. Taksit seçeneklerini PayTR belirler; bu sürümde eklenti tarafında taksit kontrolü yoktur.

Siparişi korumak için tasarlanmış kurallar

Ödeme entegrasyonlarının en sık yarattığı sorunlar çift ödeme, eksik tahsilat ve sahte onaydır. Eklenti bunlara karşı açık kurallarla çalışır:

• Yinelenen bildirimler: Aynı bildirim iki kez gelirse ikinci kez etki üretmez, ancak PayTR’ye yine de beklenen onay yanıtı verilir.
• Eksik tahsilat: Toplanan tutar sipariş tutarından düşükse kayıt incelemeye alınır ve sipariş onaylanmaz.
• Tek girişim kuralı: Bir sipariş için aynı anda yalnızca bir ödeme girişimi sürebilir. Her yeni girişim yeni bir merchant_oid alır ve yalnızca önceki girişim kesin olarak başarısız ya da kapalı olduğunda başlar.
• Kesin başarısız girişim: Başarısız kapanmış bir girişim sonradan ödendi durumuna geçemez.
• El ile “Ödendi” işaretleme: PayTR’den doğrulanmış başarı kaydı yoksa siparişi elle ödendi yapmak engellenir.

Bu kurallar, mağaza ekibinin iyi niyetli bir hatasıyla bile finansal tutarsızlık oluşmasını zorlaştırır.

İade: iki adım, açık sorumluluk

İade işlemleri her zaman bir yönetici tarafından başlatılır ve iki adımda ilerler:

1. Önizleme: Sunucu iade tutarını, kalan bakiyeyi ve kaynağı (sipariş ya da onaylı iade talebi) hesaplar. Sipariş düzeyindeki istisnai iadelerde gerekçe girmek zorunludur.
2. Onay: PayTR’ye tek bir para hareketi isteği gönderilir.

Sonucu belirsiz kalan iadeler (zaman aşımı, hatalı yanıt, bağlantı sorunu) “bilinmiyor” ya da “gönderiliyor” durumunda kalır. İkisi de “gönderilmiş olabilir” anlamına gelir. Bu iadeler yeniden gönderilmez; tutar rezerve edilir ve çözüm durum sorgusu ile mutabakat üzerinden yapılır. Başarılı bir iade, sipariş durumunu, iade talebi durumunu, toplamları, vergiyi, stoğu ya da satıcı ödemelerini yeniden hesaplamaz; yalnızca para hareketini kaydeder. Bu ayrım, muhasebe ve operasyon süreçlerinizi kendi kurallarınızla yürütmenizi sağlar.

Durum sorgusu ve mutabakat

• Durum sorgusu (salt okunur): PayTR’ye imzalı bir sorgu gönderir ve yerel kaydı PayTR’nin yanıtıyla yan yana gösterir. Hiçbir şeyi değiştirmez; ham yanıt saklanmaz. İlgili izne sahip herkes çalıştırabilir.
• Mutabakat (yetkili işlem): Ayrı bir izin, önizleme ve ayrı bir onay gerektirir. Onay anında PayTR’den taze veri çeker; ekranda görünene güvenmez.

Mutabakat şunları yapabilir: üye işyeri, merchant_oid, tutar, para birimi ve test/canlı bağlamı eşleşen tek bir ödemeyi sonlandırmak; referansı ve tutarı eşleşen belirsiz bir iadeyi çözmek; yalnızca PayTR tarafında bulunan ve tek geçerli referansı olan bir iadeyi içeri almak. Yapamayacakları da açıkça tanımlıdır: başarısız girişimi ödendi yapamaz, ödenmiş siparişi geri alamaz, iade gönderemez, eksik referansı tahmin edemez.

Bekleyen işler kuyruğu ve sağlık ekranı

Bekleyen PayTR işleri ekranı yalnızca yerel kayıtlardan oluşur; yenilemek PayTR’ye çağrı yapmaz. Eşik süresini aşan girişimleri, doğrulanmış ama tamamlanmamış kayıtları, kısmi tahsilat gibi incelemedeki kalemleri ve uyumsuz bildirim ya da iadeleri listeler. Bir kalemi “incelendi” işaretlemek için ayrı yetki gerekir; kimin ne zaman işaretlediği kaydedilir.

PayTR sağlık ekranı ise tablo varlığını, eklenti durumunu, para birimini, bildirim adresinin HTTPS olup olmadığını ve her ödeme yönteminin durumunu salt okunur biçimde kontrol eder. Ekran yeşil olsa bile PayTR hesabının, adres kaydının ya da her sepetin ödenebilirliğinin kanıtı sayılmaz; ekran yanlış bir güven duygusu yaratmasın diye bu sınır açıkça gösterilir.

Güvenlik tasarımı

• Kart verisi mağazaya hiç ulaşmaz.
• Merchant Key ve Salt mağazanın şifreleme anahtarıyla şifrelenir ve yalnızca yazılabilir; arayüzde tekrar gösterilmez.
• Bildirimler PayTR’nin belgelenmiş imza şemasına göre, sabit zamanlı karşılaştırmayla doğrulanır; doğrulanamayan bildirim hiçbir etki üretmez.
• Günlükler gizli anahtar, imza, jeton ya da ham PayTR yanıtı içermez; kayıtlar üzerine yazılmaz, eklenir.
• Finans ekranları yalnızca platform yöneticisine açıktır. Multi-Vendor’da satıcı yöneticileri benzer isimli bir izinle bile bu ekranlara giremez.
• Misafir müşterinin dönüş sayfasına erişimi, 24 saat sonra sona eren ve iptal edilebilen şifreli bir kanıta dayanır.
• Güvenilir vekil (proxy) başlıkları, yalnızca yapılandırdığınız güvenilir ağlardan kabul edilir.

Anahtar değişimi, durdurma ve geri alma

Merchant Key ya da Salt değiştiğinde eklenti önceki sürümü, yoldaki bildirimler için saklar. Bekleyen girişimler önceki sürüme bağlıyken ikinci değişiklik reddedilir. Normal durdurmada ödeme yöntemi pasife alınır, böylece yeni ödeme başlamaz; bekleyen kuyruk boşalana kadar bildirim adresi açık tutulur. Eklenti, bekleyen bildirim varken devre dışı bırakılmayı reddeder. Geri almada yeni ödemeler durdurulur, kuyruk kontrol edilir, veritabanı ve dosyalar yedeklenir, üç finans tablosu ve olay günlükleri korunur ve sonuçlar doğrulanır.

Kurulum ve gereksinimler

Kurulumdan sonra ilk yapılandırma test modunda ve yeni ödeme kabulü kapalıyken yapılır. Bildirim adresi PayTR panelinde tanımlanır; adres CS-Cart’ın ödeme bildirimi uç noktasına işaret eder. Bu çalışmayı siz yapmak zorunda değilsiniz: ekibimiz kurulumu, yetkilendirmeyi ve test senaryolarını üstlenir.

Canlıya geçiş kontrol listesi

• Ana para birimi TRY.
• Bildirim adresi HTTPS, herkese açık ve PayTR’de kayıtlı.
• crypt_key yedeklenmiş ve varsayılan değil.
• Üç izin yalnızca doğru gruplara verilmiş.
• Test modunda en az bir başarılı ödeme, bir başarısız ödeme ve bir iade denenmiş.
• Bekleyen işler kuyruğu boş.
• Vekil arkasındaysanız güvenilir ağlar tanımlı.
• İade yetkisi yalnızca gerekli kişilerde.
• Veritabanı ve dosya yedekleri güncel.

Canlıya geçişte kuyruk temizlenir, canlı bilgiler girilir, mod canlıya alınır, adres PayTR’de doğrulanır ve küçük tutarlı gerçek bir ödeme ile iade denenir.

Bilinen sınırlar

• Yalnızca TRY desteklenir; çoklu para birimi yoktur.
• Taksit kontrolü eklenti tarafında yoktur; seçenekleri PayTR sunar.
• Otomatik mutabakat yoktur; mutabakat yetkili kullanıcı tarafından başlatılır.
• Satıcılar PayTR işlemlerini göremez; finans ekranları platform yöneticisine özeldir.

Hangi durumda PayTR, hangi durumda iyzico?

Bu soruya evrensel bir cevap yoktur. Seçim; anlaşma koşullarınıza, taksit politikanıza, ödeme kuruluşuyla ilişkinize ve operasyon tercihlerinize bağlıdır. Eklentilerimiz aynı mağazada yan yana tanımlanabildiği için iki kuruluşu birlikte sunmak ya da birini yedek olarak tutmak mümkündür. iyzico Sanal POS eklentimizin ayrıntılarını da inceleyerek karar verebilirsiniz.

Proje nasıl ilerler?

1. Ödeme akışı analizi: Kullandığınız para birimi, taksit politikanız, iade sıklığınız ve hangi ekibin iade yetkisine sahip olacağı konuşulur.
2. PayTR hesabı ve bilgiler: Mağaza numarası, Merchant Key ve Salt temin edilir; crypt_key yedeği ve güvenli saklama kontrol edilir.
3. Eklenti kurulumu: Tek mağaza ya da Multi-Vendor paketi kurulur; üç yetki yalnızca doğru gruplara verilir.
4. Test modunda yapılandırma: Bildirim adresi PayTR panelinde tanımlanır; yeni ödeme kabulü kapalıyken ilk testler yapılır.
5. Senaryo testleri: En az bir başarılı ödeme, bir başarısız ödeme ve bir iade denenir; bekleyen işler kuyruğunun boş olduğu doğrulanır.
6. Canlıya geçiş: Canlı bilgiler girilir, mod canlıya alınır, adres PayTR’de doğrulanır ve küçük tutarlı gerçek bir ödeme ve iade denenir.
7. İzleme: İlk günlerde sağlık ekranı ve bekleyen işler kuyruğu düzenli izlenir.

Maliyeti ne belirler?

Çalışma kalem kalem tekliflendirilir. Etkenler: tek mağaza ya da Multi-Vendor olması, mevcut ödeme akışından geçiş (eski bir ödeme yönteminden PayTR’ye taşıma), özel iade ve onay süreçleri, ekibin eğitimi, sunucunun vekil (proxy) arkasında olup olmadığı ve canlı öncesi test yoğunluğu. PayTR’nin komisyon ve hesap koşulları PayTR ile aranızdadır; bu çalışmanın kapsamında değildir.

Finans ekibine öneriler

• İade yetkisini yalnızca gerekli kişilere verin ve gerekçe girişini zorunlu bir prosedür olarak uygulayın.
• Haftalık olarak bekleyen işler kuyruğunu ve sağlık ekranını gözden geçirin.
• Kısmi tahsilat gibi incelemedeki kalemleri aynı gün sonuçlandırın; bekleyen kalem, muhasebe kapanışını geciktirir.
• Merchant Key ve Salt değişikliklerini planlı ve tek kişiyle yapın; ikinci değişiklik, önceki sürüme bağlı bekleyen girişim varken reddedilir.
• Destek talebi açarken sipariş numarasını, PayTR referansını ve gerekçe kodunu ekleyin; Merchant Key ve Salt asla paylaşılmamalıdır.

Sık sorulan sorular

Taksit seçeneklerini mağazadan yönetebilir miyim?

Bu sürümde eklenti tarafında taksit kontrolü yoktur; müşteriye sunulan taksit seçeneklerini PayTR belirler. Taksit politikanızı PayTR panelindeki anlaşma koşullarınızla yönetirsiniz.

Müşteri ödedi ama sipariş ödenmemiş görünüyor, ne yapmalıyım?

Önce siparişteki PayTR ödeme adımları sekmesine ve bekleyen işler kuyruğuna bakın. Bildirim adresinin HTTPS ile erişilebilir olduğunu doğrulayın. Gerekirse durum sorgusuyla PayTR’deki kaydı karşılaştırın; eşleşiyorsa yetkili kullanıcı mutabakatla ödemeyi sonlandırabilir.

İadeyi yanlışlıkla iki kez gönderebilir miyim?

Eklenti buna karşı tasarlanmıştır: iade iki adımlıdır, belirsiz sonuçlu iadeler yeniden gönderilmez ve tutar rezerve edilir. Belirsiz bir iade, durum sorgusu ve mutabakatla çözülür.

Birden çok para birimiyle satış yapabilir miyim?

Hayır. Bu sürümde yalnızca TRY desteklenir ve mağazanın ana para birimi de TRY olmalıdır; dönüştürülmüş tutarlar gönderilmez.

Eklentiyi geri almam gerekirse ne olur?

Önce ödeme yöntemini pasife alın, böylece yeni ödeme başlamaz; bekleyen kuyruk boşalana kadar bildirim adresini açık tutun, yedek alın ve gerekirse eski sürümü geri yükleyin. Üç finans tablosu ve olay günlükleri her durumda korunur.

SoftCrafter ile çalışmak

Ödeme entegrasyonu, doğru kurulduğunda görünmez; yanlış kurulduğunda her gün para kaybettirir. SoftCrafter, CS-Cart’ın resmi partneri olarak eklentiyi mağazanıza kurar, test senaryolarını birlikte yürütür, canlıya geçişi yönetir ve yayın sonrası bakım ve destek seçenekleriyle yanınızda kalır. 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 ve formu bıraktığınızda ekibimiz sizi 15 dakika içinde arar. Eklentinin ayrıntılı Türkçe dokümantasyonu docs.softcrafter.dev adresindedir; daha geniş bir bakış için sanal POS entegrasyonu sayfamıza da göz atabilirsiniz.