WooCommerce iyzico ve PayTR Ödeme Eklentisi Kurulumu: Anahtarlar, Test ve Bildirim URL

Başlamadan önce

• Üye işyeri hesabı: Ödeme kuruluşuna başvurunuzun onaylanmış olması gerekir. Test ortamı için iyzico ayrı bir sandbox hesabı sunar.
• SSL: Siteniz https:// ile açılmalı. PayTR, bildirim adresi protokolünü bu duruma göre seçmenizi istiyor.
• Para birimi: Mağaza para biriminin WooCommerce > Settings > General ekranında doğru ayarlandığını kontrol edin; iyzico eklentisi ödeme isteğine mağazanın para birimini gönderir. Ayrıntılar Türkiye ayarları yazısında.
• Kalıcı bağlantılar: iyzico'nun bildirim adresi WordPress REST API üzerinden (/wp-json/) çalışır; kalıcı bağlantı yapısının Düz olmaması gerekir.
• Yedek ve test kopyası: Ödeme eklentisi kurmadan önce yedek alın; mümkünse önce bir test kopyasında deneyin.

iyzico eklentisi kurulumu

iyzico'nun resmi belgesi, modülün eklentisiz yalın bir WooCommerce kurulumunda geliştirilip test edildiğini özellikle belirtiyor. Ödeme sayfasını değiştiren başka eklentileriniz varsa önce bunlar kapalıyken test edin.

• Eklentiler > Yeni Ekle ekranında iyzico-woocommerce arayın, iyzico tarafından yayımlanan eklentiyi kurun ve etkinleştirin.
• WooCommerce > Settings > Payments ekranında iyzico ödeme yöntemini açın ve yönetim sayfasına girin.
• Enable/Disable alanında iyzico ödeme formunu etkinleştirin.
• Environment alanında test için Sandbox / Test, gerçek satış için Live seçin. Eklentinin kaynak koduna göre varsayılan değer Sandbox'tır.
• API Key ve Secret Key alanlarına seçtiğiniz ortamın anahtarlarını yapıştırın.
• Ödeme yönteminin müşteriye görünen başlığını ve açıklamasını düzenleyin.
• Payment Form Design (Türkçe arayüzde Ödeme Formu Görünümü) alanında Responsive, Popup veya Redirect seçeneklerinden birini seçin.
• Order Status alanını, eklentinin önerdiği gibi Default bırakın; ödeme formu dilini Türkçe seçin ve kaydedin.

Anahtarlar nereden alınır?

iyzico belgesine göre sandbox hesabını sandbox-merchant.iyzipay.com adresinden açarsınız; anahtarlar soldaki menüde Ayarlar > Firma Ayarları sayfasının altındaki API Anahtarları bölümünde, Görüntüle düğmesiyle görünür. Canlı hesapta da anahtarlar üye işyeri panelinin ayarlar bölümündedir. Sandbox anahtarları sandbox- önekiyle başlar ve canlı anahtarlardan tamamen farklıdır.

Webhook (ödeme bildirimi) kurulumu

Müşteri ödemeyi yaptıktan sonra tarayıcısını kapatırsa veya bağlantısı koparsa sipariş WooCommerce'te güncellenmeyebilir. iyzico belgesi, bu durumda siparişlerin doğru işlenmesi için webhook kullanılmasını öneriyor:

• iyzico ödeme ayarları sayfasında, Secret Key alanının hemen altında sitenize özel üretilmiş Webhook URL adresini kopyalayın. Adres https://alanadiniz.com/wp-json/iyzico/v1/webhook/... biçimindedir.
• iyzico üye işyeri paneline giriş yapın, soldaki menüden Ayarlar > Firma Ayarları sayfasını açın.
• İşyeri Bildirimleri bölümündeki URL alanına adresi yapıştırın, Ödeme bildirimlerini gönder seçeneğini açın ve kaydedin.
• iyzico belgesine göre webhook imza (signature) özelliğinin hesabınızda açılması için kayıtlı e-posta adresinizden iyzico entegrasyon ekibine talep iletmeniz gerekir.

Sandbox'ta test

iyzico, sandbox ortamında gerçek kartla ödemeyi desteklemez; test kartları kullanılır. Belgedeki başarılı test kartlarından biri 5526080000000006 (Akbank, Mastercard, kredi kartı). Son kullanma tarihi ileri bir tarih, CVV ise doğru biçimde rastgele bir değer olabilir; sandbox'ta SMS doğrulama şifresi her zaman 123456'dır. Başarılı ödemeden sonra siparişin durumunun değiştiğini ve iyzico sandbox panelinde işlemin göründüğünü kontrol edin.

PayTR eklentisi kurulumu

• Eklentiler > Yeni Ekle ekranında PayTR arayın ve PayTR Sanal POS WooCommerce - iFrame API eklentisini kurup etkinleştirin. Geliştirici hesabı PayTR'nin kendisidir.
• WooCommerce > Settings > Payments ekranında PayTR ödeme yöntemini açın ve yönetim sayfasına girin.
• Mağaza No, Mağaza Parola ve Mağaza Gizli Anahtar alanlarını doldurun (İngilizce arayüzde Merchant ID, Merchant Key, Merchant Salt). PayTR bu bilgileri Mağaza Panelindeki bilgi sayfasının API entegrasyon bilgileri bölümünde gösteriyor.
• Test aşamasında Test Mode kutusunu işaretleyin.
• Sipariş Durumu alanında başarılı ödeme sonrası sipariş durumunu seçin; eklenti işleniyor (processing) durumunu öneriyor.
• Taksit kullanacaksanız Taksit ayarlarını ve taksit farkının siparişe yansıtılmasını sağlayan Vade Farkı seçeneğini gözden geçirin, ödeme sayfası dilini seçip kaydedin.

Eklenti paketinde ayrıca bir Havale/EFT ödeme yöntemi bulunur. Ürün sayfasında taksit tablosu göstermek isterseniz PayTR'nin ayrı yayımladığı PayTR Taksit Tablosu - WooCommerce eklentisini kullanabilirsiniz.

Bildirim URL ayarı

PayTR'de ödeme sonucu, müşterinin yönlendirildiği sayfadan değil, PayTR sunucusunun sitenizdeki bildirim adresine gönderdiği istekten öğrenilir. Eklentinin ayar sayfası kullanmanız gereken adresi gösterir:

https://alanadiniz.com/index.php?wc-api=wc_gateway_paytrcheckout

• PayTR Mağaza Panelinde Ayarlar sayfasındaki Bildirim URL Ayarı (Callback URL) bölümünde Değiştir'e tıklayın.
• Listeden WooCommerce seçeneğini seçin ve kaydedin.
• Sitenizde SSL varsa protokol olarak https:// seçin. Sonradan SSL kurarsanız bu ayarı da güncelleyin.

Test işlemi ve canlıya geçiş

PayTR'nin modül belgesine göre ödeme ekranında test modu ekranını görüyorsanız, mağazanızın canlı moda geçmesi için önce 1 veya 2 test işlemi yapmanız gerekir. Geliştirici belgesine göre test ödemesi panelin İşlemler sayfasında Başarılı görünüyorsa entegrasyon tamamdır; Devam Ediyor görünüyorsa bildirim adresinden beklenen yanıt alınamamıştır ve işlemin Detay bölümünden hangi yanıtın döndüğüne bakmalısınız. Test bitince Test Mode kutusunun işaretini kaldırmayı unutmayın.

3D Secure ve kart verisi

Her iki eklentide de kart bilgisi sizin sitenizin formuna değil, ödeme kuruluşunun formuna girilir: iyzico'da ödeme formu (popup, responsive veya yönlendirme), PayTR'de ise sayfanıza gömülen iFrame. 3D Secure doğrulaması da bu akışın içinde ödeme kuruluşu tarafından yürütülür. Bu yapı kart verisinin sunucunuza hiç uğramaması anlamına gelir; sizin sorumluluğunuz siteyi güncel ve güvenli tutmak, SSL'i açık tutmak ve bildirim adresinin çalışmasını sağlamaktır.

Bildirim adresi neden bu kadar önemli?

PayTR'nin geliştirici belgesi bu konuda net: başarılı ödeme sonrası müşterinin yönlendirildiği sayfa siparişi onaylayacağınız yer değildir. Ödemenin sonucu bildirim adresine gelen istekteki durum bilgisiyle belirlenir. Belgeye göre:

• Bildirime yalnızca düz metin olarak OK yanıtı dönülmelidir; öncesinde veya sonrasında HTML ya da başka bir çıktı olmamalıdır. Eklenti bunu sizin için yapar, ama araya giren bir güvenlik eklentisi, bakım modu sayfası veya PHP uyarısı yanıtı bozabilir.
• Aynı ödeme için birden fazla bildirim gelebilir; eklenti bunları sipariş numarasıyla eşleştirir.
• Bildirimdeki hash değeri doğrulanır; Mağaza Parola veya Gizli Anahtar yanlışsa doğrulama başarısız olur.

iyzico tarafında da aynı mantık geçerlidir: webhook, müşterinin tarayıcısından bağımsız olarak siparişin güncellenmesini sağlar. Bu yüzden önbellek, güvenlik duvarı ve bot koruması kurallarınızın /wp-json/iyzico/ ve wc-api=wc_gateway_paytrcheckout adreslerine gelen istekleri engellemediğinden emin olun. LiteSpeed Cache ayarları için LSCache rehberine ve WooCommerce hızlandırma yazısına bakın.

Sık karşılaşılan hatalar

Hata ayıklarken önce kayıtlara bakın: WooCommerce > Status > Logs ekranı, iyzico ayarlarındaki Request Log seçeneği ve PayTR ayar sayfasındaki Hata Geçmişi bölümü. Ödeme sayfasındaki genel sorunlar (oturum süresi doldu, sipariş beklemede kaldı, yönlendirme döngüsü) için WooCommerce ödeme sayfası hataları yazısına, karma içerik uyarıları için karma içerik rehberine bakın.

Canlıya geçiş kontrol listesi

• Test modunda en az bir başarılı ve bir başarısız ödeme denendi, sipariş durumları doğru değişti.
• iyzico'da Environment Live ve canlı anahtarlar girildi; PayTR'de Test Mode kapatıldı.
• Bildirim adresleri ödeme kuruluşunun panelinde kayıtlı ve https ile.
• Canlıda küçük tutarlı gerçek bir sipariş verilip WooCommerce iade akışıyla iade edildi.
• Sipariş e-postaları müşteriye ve size ulaşıyor.
• Ödeme sayfasında şartlar ve gizlilik bağlantıları görünüyor; yasal metinler için ön bilgilendirme formu ve mesafeli satış sözleşmesi yazılarına bakın.
• Mağaza görünürlüğü WooCommerce > Settings > Site visibility ekranında Live yapıldı.

Sık Sorulan Sorular

iyzico ve PayTR'yi aynı anda kullanabilir miyim?

WooCommerce birden fazla ödeme yöntemini aynı anda etkin tutmanıza izin verir; müşteri ödeme sayfasında birini seçer. Her iki kuruluşla da ayrı sözleşmeniz olmalıdır. Ödeme sayfasını sade tutmak için çoğu küçük mağaza tek kart ödeme yöntemiyle başlar.

Eklentiler ücretli mi?

İki eklenti de WordPress.org'dan ücretsiz indirilir. İşlem başına alınan bedel ve diğer koşullar ödeme kuruluşuyla yaptığınız sözleşmeye bağlıdır; bunları doğrudan firmadan öğrenin.

Ödeme alındı ama sipariş beklemede görünüyor, neden?

Çoğunlukla ödeme sonucu bildirimi siteye ulaşmamıştır. iyzico'da webhook adresinin panelde kayıtlı olduğunu, PayTR'de Bildirim URL ayarını ve işlem detayındaki yanıtı kontrol edin; güvenlik eklentisi veya önbellek kurallarının bu adresleri engellemediğinden emin olun.

Test kartıyla canlı modda deneme yapabilir miyim?

iyzico test kartları yalnızca sandbox ortamında çalışır ve sandbox'ta gerçek kart kullanılamaz. PayTR'de yeni mağazalar test modunda başlar ve canlıya geçmeden önce test işlemi yapılması istenir; test kartı bilgilerini PayTR'nin geliştirici belgesinden alın.

Yazılım, eklenti ve hizmet adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen şirketlerle bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: WooCommerce kurulumu · WooCommerce Türkiye ayarları · WooCommerce ödeme sayfası hataları · WooCommerce hızlandırma · iyzico ödeme entegrasyonu (API) · E-ticaret sitesi nasıl kurulur · Let's Encrypt SSL kurulumu