WooCommerce PayTR Sanal POS Entegrasyonu

Türkiye'de WooCommerce ile bir mağaza kurduğunuzda ilk büyük eşik, ürünleri listelemek değil; kredi kartıyla tahsilat yapabilmektir. Kapıda ödeme ve havale/EFT bir süre işi görür, ancak müşteri terk oranlarını gerçekten düşüren, tek tıkla kart çekmenizi sağlayan bir sanal POS'tur. PayTR, banka POS anlaşmalarının uzun sürecini kısaltan, WooCommerce'e resmi eklentisiyle kolayca bağlanan ve taksit desteğini kutudan çıkar çıkmaz sunan bir sanal POS sağlayıcısıdır. Bu rehber, mağaza numarasından merchant anahtarlarına, iFrame ile Direct API tercihinden test kartlarına kadar tüm kurulumu, kıdemli bir sistem yöneticisinin bir müşteriye anlatacağı netlikte adım adım ele alıyor.

Bu yazıyı okuduktan sonra elinizde çalışan bir ödeme akışı olacak: müşteri sepeti onaylayacak, PayTR'nin güvenli ekranında kartını girecek, 3D Secure doğrulamasını geçecek ve sipariş WooCommerce tarafında otomatik olarak "işleniyor" durumuna geçecek. Henüz WooCommerce'i yeni kuruyorsanız önce WooCommerce'e başlangıç rehberimize göz atmanızı, ardından buraya dönmenizi öneririm. Ödeme entegrasyonu, mağazanın kalbidir; yanlış yapılandırma doğrudan gelir kaybı demektir, bu yüzden her adımı acele etmeden takip edin.

PayTR Sanal POS Neden Tercih Edilir#

Klasik banka sanal POS'larında süreç uzundur: bankayla anlaşma, üye iş yeri numarası, ayrı ayrı entegrasyon dokümanları ve çoğu zaman farklı bankalar için farklı kod. PayTR bu karmaşıklığı tek bir çatı altında toplar. Tek bir anlaşmayla birden fazla bankanın kartlarını kabul eder, taksit oranlarını merkezî panelden yönetir ve WooCommerce için hazır bir eklenti sunar. Bu, teknik ekibi olmayan küçük işletmeler için ciddi bir zaman ve maliyet tasarrufudur.

Öne çıkan avantajları pratik olarak şöyle özetleyebiliriz:

• Hızlı başvuru: Şahıs şirketi veya limited şirketle, evrakları yükledikten sonra genellikle birkaç iş günü içinde onay alırsınız. Banka POS'undaki haftalarca süren bekleme yoktur.
• Taksit desteği: Kart bankasına göre 2 ila 12 taksit seçeneği ödeme ekranında otomatik listelenir. Taksit maliyetini müşteriye yansıtmak veya "taksit farksız" kampanya kurmak panelden yönetilir.
• Tek entegrasyon, çok banka: Müşterinin kartı hangi bankaya aitse PayTR uygun POS'a yönlendirir; sizin ayrı entegrasyon yapmanız gerekmez.
• 3D Secure zorunluluğu: Ödemeler 3D Secure ile doğrulandığı için "chargeback" (ters ibraz) riski önemli ölçüde azalır; sorumluluk büyük ölçüde kart sahibine geçer.
• BKM ve tahsilat raporları: Günlük hakediş, komisyon ve taksit raporlarını panelden çekebilir, muhasebeyle uyumlu tutarsınız.

Kısaca PayTR, "banka POS'unun bürokrasisi olmadan kredi kartı tahsilatı" ihtiyacına yönelik pratik bir çözümdür. Aşağıdaki bölümlerde teknik kurulumun tamamını göreceğiz.

Başvuru ve Mağaza Bilgilerini Edinme#

Entegrasyona başlamadan önce PayTR üye iş yeri hesabınızın açılmış ve onaylanmış olması gerekir. Başvuru sırasında şirket bilgileri, vergi levhası, imza sirküleri ve web sitenizin adresi istenir. Site adresi olarak, ödeme alacağınız gerçek alan adını (örneğin magazam.com) girmelisiniz; test aşamasında bile alan adının canlı ve SSL sertifikalı olması onay sürecini hızlandırır. Henüz alan adınız yoksa alan adı kayıt sayfamızdan hızlıca temin edebilirsiniz.

Hesap onaylandıktan sonra PayTR panelinde Ayarlar bölümünde üç kritik değer sizi bekler. Bu değerler entegrasyonun kimlik kartıdır ve gizli tutulmalıdır:

Bu üç değeri bir kenara güvenli biçimde not edin. Özellikle Merchant Key ve Merchant Salt değerleri, ödeme isteklerinin bütünlüğünü doğrulayan hash'i ürettiği için asla istemci tarafına (tarayıcıya, JavaScript'e) düşmemelidir. Bunlar yalnızca sunucu tarafında, WordPress veritabanında ve PHP tarafında saklanır. WooCommerce eklentisi bu değerleri şifreli veya en azından wp_options tablosunda tutar; paylaşımlı hosting kullanıyorsanız dosya izinlerinin doğru olması bu yüzden önemlidir.

Panelde ayrıca Test Modu anahtarını da göreceksiniz. Entegrasyonu tamamlayana kadar bu modu açık bırakmanızı öneririm; böylece gerçek para hareketi olmadan tüm akışı deneyebilirsiniz.

WooCommerce Tarafinda Kurulum Adimlari#

Artık anahtarlar elimizde; sırada WordPress tarafı var. Kurulumun temeli, resmi PayTR WooCommerce eklentisini yükleyip yukarıdaki üç değeri girmektir. Eklentiyi WordPress yönetim panelinden Eklentiler → Yeni Ekle yoluyla aratabilir ya da PayTR'nin sağladığı zip dosyasını yükleyebilirsiniz. WP-CLI kullanıyorsanız sunucuda tek satırla da hallolur:

# WordPress kök dizininde, WP-CLI ile eklenti kurulumu
wp plugin install woocommerce-paytr --activate

# Etkin eklentileri doğrula
wp plugin list --status=active --field=name

Eklenti etkinleştikten sonra WooCommerce → Ayarlar → Ödemeler sekmesine gidin. Listede "PayTR iFrame" veya "PayTR Sanal POS" adlı bir yöntem göreceksiniz. Bunu etkinleştirip Yönet butonuna tıkladığınızda karşınıza anahtarları gireceğiniz form çıkar. Alanları şöyle doldurun:

• Mağaza No: Panelden aldığınız Merchant ID.
• Mağaza Anahtarı (Merchant Key): İmzalama anahtarı.
• Mağaza Gizli Anahtarı (Merchant Salt): Tuz değeri.
• Test Modu: Kurulum bitene kadar "Açık".
• Başlık ve Açıklama: Müşterinin ödeme adımında göreceği metin, örneğin "Kredi/Banka Kartı ile Güvenli Ödeme".

Değerleri elle girmek yerine sunucuya doğrudan yazmak isterseniz, WooCommerce ayarları wp_options tablosunda serialize edilmiş biçimde tutulur. WP-CLI ile programatik olarak da atayabilirsiniz:

# PayTR ayar dizisini WP-CLI ile güncelle (örnek anahtarlar)
wp option patch update woocommerce_paytr_settings merchant_id "123456"
wp option patch update woocommerce_paytr_settings merchant_key "AbCdEf123456"
wp option patch update woocommerce_paytr_settings merchant_salt "XyZ987654321"
wp option patch update woocommerce_paytr_settings testmode "yes"

Ayarları kaydettikten sonra mağazanızın ön yüzüne geçip bir ürünü sepete ekleyin ve ödeme adımına ilerleyin. PayTR yöntemi listede görünüyorsa temel bağlantı kurulmuş demektir. Eklenti kurulumu ve yönetimi konusunda genel bir bakış için WordPress eklenti önerileri rehberimiz de faydalı olacaktır.

iFrame mi Direct API mi#

PayTR, ödeme ekranını iki farklı yöntemle sunar ve WooCommerce entegrasyonunuzda bunlardan birini seçersiniz. Bu tercih, hem güvenlik yükünüzü hem de müşteri deneyimini doğrudan etkiler, bu yüzden bilinçli karar vermek önemlidir.

iFrame (gömülü ödeme ekranı): Kart bilgilerini toplayan formu PayTR'nin kendi sunucusu üretir ve sitenize bir iFrame içinde gömülür ya da tam sayfa yönlendirmeyle gösterilir. Kart numarası hiçbir zaman sizin sunucunuza uğramaz; doğrudan PayTR'ye gider. Bu, PCI-DSS yükümlülüğünüzü büyük ölçüde azaltır çünkü hassas kart verisini siz işlemezsiniz.

Direct API (doğrudan API): Kart formunu kendi sitenizde oluşturur, kart bilgilerini kendi sunucunuzda toplayıp PayTR API'sine gönderirsiniz. Tasarım üzerinde tam kontrol sağlar ancak kart verisi sunucunuzdan geçtiği için PCI-DSS uyumluluğu ve çok daha sıkı güvenlik sizin sorumluluğunuza girer.

İki yöntemi karşılaştıralım:

Deneyimlerime göre WooCommerce mağazalarının büyük çoğunluğu için iFrame doğru seçimdir. Güvenlik sorumluluğunu PayTR'ye devreder, entegrasyon süresini kısaltır ve resmi eklentinin varsayılan modudur. Direct API'yi yalnızca özel bir ödeme deneyimi tasarlamanız gereken, güvenlik ekibiniz olan ve PCI-DSS yükünü üstlenebilecek büyük operasyonlarda değerlendirin. Bu rehberin geri kalanında iFrame yöntemini esas alıyoruz.

Callback URL ve Bildirim Ayarlari#

Ödeme entegrasyonunun en çok atlanan ama en kritik parçası callback (bildirim) URL'sidir. Müşteri ödemeyi tamamladığında PayTR, tarayıcıyı sitenize geri yönlendirir; ancak asıl siparişi "ödendi" olarak işaretleyen şey bu yönlendirme değil, PayTR sunucusunun arka planda sitenize gönderdiği sunucudan sunucuya bildirimdir. Müşteri tarayıcıyı erken kapatsa bile bu bildirim geldiği için sipariş kaybolmaz.

Resmi eklentide callback URL çoğunlukla otomatik ayarlanır ve şu biçimdedir:

https://magazam.com/?wc-api=paytr_iframe

Bu adresi PayTR panelindeki Bildirim URL alanına da girmelisiniz. Adresin dışarıdan erişilebilir, HTTPS'li ve önünde bir "bakım modu" ya da IP kısıtlaması olmayan bir yol olması şarttır; aksi halde PayTR bildirimi teslim edemez ve ödemeler alınmasına rağmen sipariş "beklemede" kalır. Eğer sunucunuzda Nginx varsa, bu yolun WordPress'e sağlıklı ulaştığından emin olun:

# WordPress kalıcı bağlantılar — PayTR callback'i de bu blokla eşleşir
location / {
    try_files $uri $uri/ /index.php?$args;
}

# PHP-FPM işleme
location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Callback'in gelip gelmediğini kontrol etmenin en pratik yolu web sunucusu erişim loglarını izlemektir. Bir test ödemesi yaptıktan sonra loglarda PayTR'nin isteğini aramalısınız:

# Erişim loglarında PayTR callback isteklerini süz
tail -f /var/log/nginx/access.log | grep "wc-api=paytr"

Eğer bu istek loglarda hiç görünmüyorsa sorun büyük olasılıkla güvenlik duvarı, WAF kuralı veya yanlış bildirim URL'sidir. Sunucu tarafında saldırı filtreleme kullanıyorsanız PayTR'nin bildirim gönderen IP aralıklarının engellenmediğinden emin olun; bu tür ince ayarlar için WAF hizmetimiz ve sunucu yönetimi desteğimiz devreye girebilir.

Test Kartlariyla Dogrulama#

Canlıya geçmeden önce mutlaka test modunda uçtan uca bir deneme yapın. Test modu açıkken PayTR gerçek para çekmez; bunun yerine sağladığı sahte kart numaralarıyla başarılı ve başarısız senaryoları taklit edebilirsiniz. Amaç, sipariş durumlarının doğru değiştiğini ve callback'in çalıştığını görmektir.

Tipik bir test akışı şöyle ilerler:

1. Test modunu hem WooCommerce eklentisinde hem PayTR panelinde "açık" konuma getirin.
2. Mağazadan bir ürünü sepete ekleyip ödeme adımına geçin.
3. PayTR'nin sağladığı test kart numarasını, geçerli bir son kullanma tarihi ve CVV ile girin.
4. 3D Secure test doğrulamasını (genellikle sabit bir şifre) tamamlayın.
5. Sipariş sayfasına dönüldüğünde durumun "İşleniyor" veya "Tamamlandı" olduğunu doğrulayın.

Başarılı ödeme senaryosunun yanında, başarısız senaryoyu da test etmelisiniz. Yetersiz bakiye veya reddedilen kartı taklit eden test numaralarıyla ödeme başlatın ve WooCommerce'te siparişin "Başarısız" durumunda kaldığını, stoktan düşme yapılmadığını doğrulayın. Bu iki senaryoyu ayrı ayrı görmeden canlıya geçmeyin.

Test sırasında sipariş durumlarını komut satırından da izleyebilirsiniz. WP-CLI ile son siparişlerin durumlarını hızlıca listelemek işinizi kolaylaştırır:

# Son 10 siparişi durumlarıyla listele
wp wc shop_order list --user=1 --field=id --per_page=10 | \
  xargs -I{} wp post get {} --field=post_status

Her şey yolundaysa test modunu kapatıp anahtarları koruyarak canlıya geçebilirsiniz. Canlıya geçtikten sonra da ilk gerçek işlemi mümkünse düşük tutarlı, kendi kartınızla yapıp muhasebe tarafında hakedişin panele düştüğünü teyit edin.

Siparis Durumu, SSL ve Guvenlik#

Ödeme başarıyla tamamlandığında WooCommerce siparişi genellikle İşleniyor (processing) durumuna alır; fiziksel ürün gönderdikten sonra siz "Tamamlandı" yaparsınız, dijital ürünlerde ise "Tamamlandı" otomatik olabilir. Sipariş durumu mantığını doğru kurgulamak, kargolama ve stok akışınızın tutarlı olması için kritiktir. Callback başarısız olur da sipariş "Beklemede" kalırsa, müşteri parayı ödemiş olmasına rağmen siparişi görmezden gelebilirsiniz; bu yüzden bir önceki bölümdeki callback doğrulamasını asla atlamayın.

Güvenlik tarafında pazarlık kabul etmeyen tek şart SSL sertifikasıdır. PayTR, ödeme alacağınız alan adında geçerli bir HTTPS bağlantısı olmasını zorunlu tutar; SSL olmayan bir sitede iFrame ödeme ekranı ya hiç açılmaz ya da tarayıcı "güvenli değil" uyarısıyla müşteriyi kaçırır. Ücretsiz Let's Encrypt sertifikası çoğu senaryo için yeterlidir, ancak kurumsal bir görünüm ve genişletilmiş doğrulama isterseniz SSL sertifika hizmetlerimizi inceleyebilirsiniz. Sertifikanın süresini de takip edin; süresi biten bir sertifika, ödeme akışını bir gecede durdurur.

Ek olarak şu güvenlik alışkanlıklarını edinin:

• Merchant Key ve Salt'ı gizli tutun. Bu değerleri tema dosyalarına, herkese açık depolara veya JavaScript'e asla koymayın.
• WordPress ve eklentileri güncel tutun. Ödeme akışı, çekirdek ve WooCommerce sürümlerine bağlıdır; güncelleme aksatmak açık kapı bırakır. Düzenli bakım için WordPress bakım hizmetimize bakabilirsiniz.
• Düzenli yedek alın. Ödeme ve sipariş verisi para demektir; bir sorun anında geri dönebilmek için otomatik yedekleme çözümümüzü devreye alın.
• Yeterli sunucu kaynağı ayırın. Yoğun kampanya günlerinde ödeme adımının yavaşlaması sepet terkine yol açar. Yüksek trafik bekleyen mağazalar için WordPress hosting ya da daha da güçlü bir sanal sunucu altyapısı, paylaşımlı plandan çok daha stabil bir ödeme deneyimi sunar.

Bu üç ayak — doğru sipariş akışı, kesintisiz SSL ve sıkı anahtar yönetimi — birlikte çalıştığında PayTR entegrasyonunuz hem müşteri hem de siz açısından güvenilir bir tahsilat kanalına dönüşür.

Sik Karsilasilan Sorunlar ve Cozumleri#

Kurulum sırasında en çok karşılaşılan tıkanma noktalarını ve pratik çözümlerini burada topladım. Bir sorun yaşadığınızda önce bu listeye göz atın; çoğu vaka bunlardan biridir.

• Ödeme ekranı açılmıyor: Neredeyse her zaman SSL veya yanlış anahtar sorunudur. Alan adında geçerli HTTPS olduğundan ve Merchant No/Key/Salt değerlerinin boşluksuz, doğru kopyalandığından emin olun.
• Sipariş "Beklemede" kalıyor: Callback URL'si PayTR'ye ulaşmıyor demektir. Bildirim URL'sini kontrol edin, WAF/güvenlik duvarında PayTR IP'lerinin engellenmediğini doğrulayın ve erişim loglarında wc-api=paytr isteğini arayın.
• Taksit seçenekleri görünmüyor: Taksit ayarları PayTR panelinden yönetilir. Panelde ilgili banka için taksit tanımlı değilse WooCommerce tarafında da görünmez; ayrıca sepet tutarı, tanımlı minimum taksit tutarının altındaysa taksit gizlenir.
• Test çalışıyor, canlı çalışmıyor: Test modunu kapatmayı unutmuş ya da canlı anahtarları girmemiş olabilirsiniz. Test ve canlı anahtarların aynı olduğunu, test modunun kapalı olduğunu teyit edin.
• Çift sipariş oluşuyor: Genelde eklenti veya tema çakışmasıdır. Geçici olarak diğer ödeme eklentilerini devre dışı bırakıp yeniden test edin; çakışma teşhisi için ayrı bir bakım penceresinde çalışın.

Bu adımlardan sonra sorun sürüyorsa, sunucu tarafı log analizi ve derinlemesine teşhis gerekebilir. Böyle durumlarda konuyu yönetilen bir uzmana devretmek zaman kazandırır.

Sıkça Sorulan Sorular#

PayTR entegrasyonu için ayrı bir yazılımcıya ihtiyacım var mı?#

Hayır, çoğu durumda gerek yoktur. Resmi PayTR WooCommerce eklentisini yükleyip PayTR panelinden aldığınız Mağaza No, Merchant Key ve Merchant Salt değerlerini girmeniz iFrame yöntemi için yeterlidir. Yalnızca Direct API ile özel bir ödeme akışı tasarlamak isterseniz veya sunucu tarafında callback sorunları yaşarsanız teknik destek almanız mantıklı olur.

iFrame ile Direct API arasında hangisini seçmeliyim?#

Mağazaların büyük çoğunluğu için iFrame yöntemi doğru tercihtir. iFrame'de kart bilgileri doğrudan PayTR'ye gittiği için PCI-DSS güvenlik yükü sizin üzerinizden kalkar ve kurulum çok daha basittir. Direct API'yi yalnızca tam tasarım kontrolü gereken, güvenlik ekibi bulunan ve PCI-DSS sorumluluğunu üstlenebilecek büyük ölçekli operasyonlarda değerlendirmelisiniz.

SSL sertifikası olmadan PayTR kullanabilir miyim?#

Kullanamazsınız. PayTR, ödeme alınan alan adında geçerli bir SSL sertifikası bulunmasını zorunlu tutar. SSL olmadan ödeme ekranı açılmaz veya tarayıcı güvenlik uyarısı göstererek müşteriyi kaçırır. Ücretsiz Let's Encrypt sertifikası temel ihtiyaçları karşılar; kurumsal görünüm için ücretli bir sertifikayı tercih edebilirsiniz.

Ödeme alındı ama sipariş beklemede kaldı, neden?#

Bunun nedeni neredeyse her zaman callback bildiriminin sitenize ulaşmamasıdır. Müşterinin tarayıcı yönlendirmesi değil, PayTR sunucusunun arka planda gönderdiği sunucudan sunucuya bildirim siparişi ödendi olarak işaretler. Bildirim URL'sinin doğru, HTTPS'li ve dışarıdan erişilebilir olduğunu kontrol edin, güvenlik duvarında PayTR isteklerinin engellenmediğini doğrulayın ve web sunucusu erişim loglarını inceleyin.

Test kartlarıyla yaptığım denemede gerçekten para çekilir mi?#

Hayır, test modu açıkken hiçbir gerçek para hareketi olmaz. PayTR, başarılı ve başarısız senaryoları taklit etmeniz için özel test kart numaraları sağlar. Bu kartlarla sipariş durumlarının doğru değiştiğini ve callback'in çalıştığını güvenle doğrulayabilirsiniz. Yalnızca test tamamlandıktan sonra test modunu kapatıp gerçek anahtarlarla canlıya geçmelisiniz.

Taksit seçeneklerini nasıl yönetirim?#

Taksit oranları ve kampanyaları PayTR panelinden yönetilir, WooCommerce tarafında ekstra bir kod gerektirmez. Panelde hangi banka için kaç taksit tanımlıysa müşteri ödeme ekranında o seçenekleri görür. Sepet tutarı tanımlı minimum taksit tutarının altındaysa taksit otomatik olarak gizlenir, bu yüzden düşük tutarlı ürünlerde tek çekim görünmesi normaldir.

Kapanış#

PayTR sanal POS entegrasyonu, WooCommerce mağazanızı gerçek anlamda satış yapan bir yapıya dönüştüren adımdır. Doğru anahtarları girmek, iFrame yöntemini seçmek, callback URL'sini sağlamlaştırmak ve test kartlarıyla uçtan uca doğrulama yapmak; bu dört adımı düzgün tamamladığınızda ödeme akışınız hem müşteriye güven veren hem de sizi manuel takipten kurtaran otomatik bir sisteme dönüşür. Unutmayın: kesintisiz SSL, güncel eklentiler ve düzenli yedek, bu sistemin görünmeyen ama vazgeçilmez temelleridir.

Sağlam bir e-ticaret altyapısı, güçlü bir sunucu üzerinde başlar. Yoğun kampanya trafiğinde ödeme adımının hızlı ve stabil kalması için performanslı bir zemine ihtiyacınız var. Clou.TR'nin WordPress'e optimize hosting paketlerini, daha yüksek trafik için sanal sunucu çözümlerini ve mağazanızı baştan sona güvene alacak SSL ile yedekleme hizmetlerini inceleyerek WooCommerce mağazanızı sağlam, güvenli ve büyümeye hazır bir temele oturtabilirsiniz.