WooCommerce iyzico Odeme Entegrasyonu Kurulumu

WooCommerce ile kurduğunuz mağazada ürünleri güzelce dizmek, kargo kurallarını tanımlamak ve temayı özelleştirmek işin görünen kısmıdır; asıl para kazandıran adım ise müşterinin sepeti onaylayıp kartıyla ödeme yapabildiği andır. Türkiye'de bu tahsilat akışının en yaygın çözümlerinden biri iyzico'dur. Kredi kartı, banka kartı, taksitli ödeme ve 3-D Secure doğrulamasını tek bir panelden yönetmenizi sağlar; üstelik WooCommerce için resmî bir eklentisi olduğu için entegrasyon, kart verilerini kendi sunucunuzda tutmadan (yani PCI yükünü büyük ölçüde iyzico'ya devrederek) yapılabilir.

Bu rehberde iyzico'nun ne olduğundan başlayıp, hesap açtıktan sonra API ve secret anahtarlarını nereden alacağınıza, WooCommerce eklentisini nasıl kuracağınıza, taksit tablosunu ve 3-D Secure zorunluluğunu nasıl ayarlayacağınıza, test modunda gerçek para harcamadan nasıl deneme yapacağınıza ve son olarak iade akışını nasıl yürüteceğinize kadar tüm adımları uygulamalı olarak anlatacağım. Anlatım, daha önce ödeme entegrasyonu yapmamış bir mağaza sahibinin de takip edebileceği düzeyde; ancak WooCommerce'e zaten hakimseniz doğrudan ilgilendiğiniz bölüme atlayabilirsiniz. Henüz mağazanızı kurmadıysanız önce WooCommerce başlangıç rehberini okumanızı öneririm.

iyzico Nedir ve Neden Tercih Edilir?#

iyzico, Türkiye merkezli lisanslı bir ödeme kuruluşudur; yani BDDK/TCMB düzenlemelerine tabi, "sanal POS" hizmetini bankalarla sizin adınıza yöneten bir aracıdır. Klasik yöntemde her banka için ayrı ayrı sanal POS başvurusu yapıp her birinin kendi entegrasyonunu kodlamanız gerekirken, iyzico tüm bankaların kart altyapısını tek bir API'nin arkasında toplar. Bu, özellikle yeni açılan ve henüz bir bankayla sanal POS anlaşması olmayan mağazalar için büyük kolaylıktır.

Türk e-ticaret siteleri için iyzico'yu cazip kılan başlıca noktalar şunlardır:

• Tüm büyük bankaların kredi kartlarında taksit desteği tek entegrasyonla gelir.
• Kart bilgileri iyzico'nun güvenli sayfasında/altyapısında işlenir, sizin sunucunuza ham kart numarası düşmez.
• 3-D Secure (kartın bankası üzerinden SMS/uygulama doğrulaması) yerleşik olarak desteklenir.
• WooCommerce için resmî ve ücretsiz bir eklentisi vardır; ayrıca özel geliştirme için REST API ve SDK'lar sunar.
• İade, kısmi iade ve iptal işlemleri hem panelden hem de API üzerinden yapılabilir.

Karar aşamasında komisyon oranlarını, hakediş (para transferi) süresini ve taksit maliyetlerini mutlaka güncel iyzico sözleşmenizden teyit edin; bu değerler sektöre, ciroya ve kampanyalara göre değişir. Bu rehber teknik entegrasyona odaklandığı için ticari koşulları iyzico ile netleştirdiğinizi varsayıyorum.

Kurulum Öncesi Gereksinimler: SSL, PCI ve Hosting#

Ödeme entegrasyonuna geçmeden önce altyapının hazır olması gerekir. En kritik gereksinim SSL sertifikasıdır. Ödeme sayfasında kart bilgisi girildiği ve 3-D Secure için banka sayfasına yönlendirme yapıldığı için sitenizin baştan sona HTTPS üzerinden çalışması zorunludur. SSL'i olmayan bir sitede tarayıcılar "Güvenli Değil" uyarısı gösterir, iyzico da canlı modda genellikle HTTPS şartı arar. Sitenizde henüz sertifika yoksa SSL sertifikası sayfasından uygun bir sertifika edinip kurun, ardından WordPress adresini https:// ile güncelleyin.

WordPress ayarlarının doğru olduğunu wp-cli ile hızlıca kontrol edebilirsiniz:

# Site ve ana sayfa adresinin https ile başladığını doğrulayın
wp option get siteurl
wp option get home

# https değilse güncelleyin
wp option update siteurl 'https://magazaniz.com'
wp option update home 'https://magazaniz.com'

PCI DSS uyumu konusunda net olmak gerekir: iyzico'nun WooCommerce eklentisi "hosted" ve tokenizasyon temelli çalıştığı için ham kart numarası sizin sunucunuzda saklanmaz veya işlenmez. Bu, sizi PCI DSS'in en ağır seviyesinden büyük ölçüde muaf tutar; genellikle en basitleştirilmiş öz-değerlendirme formu (SAQ A) kapsamında kalırsınız. Yine de bu muafiyet, sitenizin güvenli olduğu anlamına gelmez: SSL'i güncel tutmak, WordPress ve eklentileri yamamak, yönetici girişini korumak sizin sorumluluğunuzdadır. Ödeme akışının önüne bir WAF koymak ve düzenli yedekleme almak, ihlal riskini ciddi biçimde azaltır.

Hosting tarafında da birkaç PHP ayarının yeterli olması gerekir. iyzico API'sine giden isteklerin ve 3-D Secure yönlendirmelerinin sağlıklı çalışması için minimum ayarlar:

; php.ini önerilen minimumlar
memory_limit = 256M
max_execution_time = 60
allow_url_fopen = On
; iyzico API'sine HTTPS istekleri için cURL uzantısı etkin olmalı
extension = curl
extension = openssl

Küçük bir katalogla başlıyorsanız paylaşımlı bir WordPress hosting paketi yeterli olur; ancak kampanya dönemlerinde eşzamanlı ödeme trafiği artıyorsa daha fazla kaynağa sahip bir hosting planına veya tam kontrol için bir sanal sunucuya geçmek mantıklıdır.

iyzico API ve Secret Anahtarlarını Alma#

iyzico ile WooCommerce arasındaki güven, iki değere dayanır: API Key ve Secret Key. Bunlar mağazanızın kimliğini doğrular; kimseyle paylaşılmaması, git deposuna veya ekran görüntüsüne düşmemesi gereken hassas bilgilerdir. iyzico'da iki ayrı ortam olduğunu bilmek önemlidir:

Anahtarları almak için önce iyzico merchant panelinize giriş yapın. Test aşaması için sandbox paneline, canlıya geçerken de production paneline ihtiyacınız olacak. Panelde genellikle "Ayarlar" veya "Geliştirici / API Anahtarları" başlığı altında API Key ve Secret Key birlikte listelenir. Buradaki iki değeri kopyalayıp güvenli bir yerde tutun.

Anahtarları düz metin dosyalarında saklamak yerine, sunucu tarafında ortam değişkeni olarak tutmak iyi bir alışkanlıktır. WordPress'te wp-config.php üzerinden tanımlayıp eklentiye oradan okutabileceğiniz senaryolar için:

# .env benzeri bir yaklaşım — anahtarları koda gömmeyin
export IYZICO_API_KEY="sandbox-XXXXXXXXXXXXXXXX"
export IYZICO_SECRET_KEY="sandbox-YYYYYYYYYYYYYYYY"

Anahtarların doğruluğunu, eklentiyi hiç kurmadan bir cURL isteğiyle de sınayabilirsiniz. Aşağıdaki istek, sandbox API'sine basit bir bağlantı denemesi yapar; kimlik doğrulama başarısızsa iyzico anlamlı bir hata döner:

# Sandbox API'sinin ayakta olduğunu ve bağlantının kurulduğunu doğrulama
curl -s -o /dev/null -w "%{http_code}\n" \
  https://sandbox-api.iyzipay.com/payment/test

# Beklenen: HTTP 200 (imza doğrulaması ayrı; bu yalnızca erişim testi)

Eğer sunucunuz bu isteği zaman aşımına uğratıyorsa, büyük ihtimalle giden bağlantılar (outbound) bir güvenlik duvarıyla engellenmiştir; hosting sağlayıcınızdan iyzico API alan adlarına giden HTTPS trafiğinin açık olduğunu teyit edin.

WooCommerce iyzico Eklentisini Kurma ve Yapılandırma#

Anahtarlar hazır olduğunda entegrasyonun görünen kısmı oldukça hızlı ilerler. iyzico eklentisini WordPress panelinden veya wp-cli ile kurabilirsiniz:

# Eklentiyi komut satırından kurup etkinleştirme
wp plugin search iyzico
wp plugin install iyzico-woocommerce --activate

# Kurulu eklentileri listeleyip sürümü doğrulama
wp plugin list --status=active

Panelden kurmak isterseniz Eklentiler > Yeni Ekle ekranında "iyzico" araması yapıp resmî eklentiyi kurup etkinleştirin. Genel eklenti hijyeni için WordPress eklenti önerileri yazısındaki güncelleme ve güvenlik ilkelerini de gözden geçirmenizi tavsiye ederim.

Etkinleştirmeden sonra ödeme yöntemi ayarlarına gidin. WooCommerce'te bu yol WooCommerce > Ayarlar > Ödemeler sekmesidir. Listede iyzico'yu görüp yönetim ekranını açtığınızda doldurmanız gereken temel alanlar şunlardır:

• API Key ve Secret Key (önce sandbox değerleriyle başlayın)
• Ödeme yönteminin başlığı ve müşteriye görünecek açıklaması
• Ortam seçimi: Test (Sandbox) / Canlı (Production)
• Taksit, 3-D Secure ve kart saklama gibi davranış ayarları

Ayarları kaydettikten sonra bir ödeme sayfası (checkout) açıp iyzico'nun ödeme seçeneği olarak listelenip listelenmediğini kontrol edin. Görünmüyorsa en sık nedenler; ödeme yönteminin "etkin" olmaması, mağaza para biriminin TRY olmaması veya SSL'in eksik olmasıdır.

Taksit Tablosu ve 3-D Secure Ayarları#

Türk müşterisinin ödeme kararında taksit seçeneği çoğu zaman belirleyicidir. iyzico tarafında taksit iki katmanda yönetilir: bir yanda iyzico merchant panelindeki taksit ve komisyon tanımları, diğer yanda WooCommerce eklentisinin hangi taksit sayılarını müşteriye göstereceği ayarı vardır. Genel mantık şudur: iyzico panelinde hangi bankalar için kaç taksit ve hangi komisyon oranıyla izin verdiğinizi belirlersiniz; eklenti de sepet tutarına ve karta göre uygun taksit seçeneklerini ödeme ekranında listeler.

Örnek bir taksit/komisyon kurgusu, karar vermeyi kolaylaştırması açısından şöyle görselleştirilebilir:

Buradaki "kime yansır" kolonu tamamen ticari tercihtir; komisyonu siz üstlenebilir (fiyata gömer) veya müşteriye vade farkı olarak yansıtabilirsiniz. Önemli olan, iyzico panelindeki tanımla eklentinin gösterdiği seçeneklerin tutarlı olmasıdır; aksi halde müşteri ödeme ekranında hata alır.

3-D Secure konusunda tavsiyem nettir: mutlaka zorunlu tutun. 3-D Secure, kartın gerçek sahibinin işlemi bankası üzerinden (SMS kodu veya banka uygulaması ile) onaylamasını sağlar. Bu, sahte kart kullanımını ciddi biçimde azaltır ve bir itiraz (chargeback) durumunda ispat yükünü kart sahibine kaydırır. iyzico eklentisinde 3-D Secure'ü zorunlu kılan seçeneği etkinleştirdiğinizde, ödeme akışı şu şekilde ilerler:

# 3-D Secure ile ödeme akışının basitleştirilmiş adımları
1_sepet_onay:      Müşteri checkout'ta iyzico'yu seçer
2_kart_bilgisi:    Kart numarası, son kullanma, CVC girilir
3_3ds_yonlendirme: Bankanın 3-D Secure sayfasına gidilir
4_dogrulama:       SMS kodu / uygulama onayı verilir
5_sonuc_donus:     iyzico sonucu WooCommerce'e bildirir
6_siparis_durumu:  Başarılıysa sipariş "processing" olur

Bazı kurumsal kartlarda veya belirli bankalarda 3-D Secure zorunlu olmayabilir; ancak "isteğe bağlı" bırakmak yerine her işlemde zorunlu tutmak, güvenlik açısından her zaman daha doğru bir varsayılandır.

Test Modu ve Canlıya Geçiş#

Entegrasyonu canlıya almadan önce sandbox (test) ortamında baştan sona en az bir başarılı ve bir başarısız ödeme senaryosu denemelisiniz. Test modunda gerçek para hareketi olmaz; iyzico'nun sağladığı sahte test kartlarıyla farklı sonuçları taklit edebilirsiniz. Yaygın test kartı senaryoları şu mantıkla çalışır:

Test kartlarının güncel numaralarını iyzico geliştirici dokümantasyonundan alın; bu numaralar zaman zaman güncellenir, bu yüzden burada sabit bir numara vermiyorum. Test sırasında dikkat etmeniz gerekenler: mağaza para biriminin TRY olması, ortam seçiminin "Test" konumunda olması ve API/Secret anahtarlarının sandbox anahtarları olması.

Test başarılı olduğunda canlıya geçiş üç adımdan ibarettir. İlki, eklentideki API ve Secret anahtarlarını sandbox değerlerinden production değerleriyle değiştirmektir. İkincisi, ortam seçimini "Canlı" konumuna almaktır. Üçüncüsü ise sandbox'ta çalışan hiçbir şeye güvenmeyip canlıda kendi kartınızla küçük tutarlı gerçek bir test alışverişi yapıp ardından o siparişi iade etmektir. Bu son adım, hakediş ve iade akışının da gerçekten çalıştığını görmenizi sağlar.

Canlıya geçtikten sonra ödeme dönüş (callback) URL'lerinin dış dünyadan erişilebilir olduğundan emin olun. Eğer sitenizin önünde bir ters vekil (reverse proxy) varsa, iyzico'dan gelen dönüş isteklerinin WordPress'e sağlıklı ulaşması için HTTPS başlıklarını doğru ilettiğinizi kontrol edin:

# Ters vekil arkasında WordPress — HTTPS'in doğru algılanması için
location / {
    proxy_pass         http://127.0.0.1:8080;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
}

X-Forwarded-Proto başlığı eksikse WordPress isteği http sanabilir ve ödeme dönüşünde karışık içerik veya yönlendirme döngüsü yaşayabilirsiniz.

İade, İptal ve Sipariş Yönetimi#

Sağlıklı bir ödeme entegrasyonu sadece parayı tahsil etmekle bitmez; müşteri cayma hakkını kullandığında veya bir sorun çıktığında iadeyi de düzgün yapabilmelisiniz. iyzico'da iki farklı işlem vardır ve bunları karıştırmamak önemlidir. İptal (cancel), aynı gün içinde ve gün sonu (hakediş) kapanmadan önce yapılan, tutarın hiç düşülmemiş gibi geri alındığı işlemdir. İade (refund), gün sonu kapandıktan sonra, tahsil edilmiş bir tutarın (tamamının veya bir kısmının) müşteriye geri gönderilmesidir.

WooCommerce tarafında iade akışı genellikle sipariş ekranından yürütülür: ilgili siparişi açar, "İade" butonuyla iade edilecek tutarı girer ve iyzico eklentisi kuruluysa "iyzico üzerinden iade et" seçeneğini işaretlersiniz. Bu, hem WooCommerce sipariş durumunu hem de iyzico tarafındaki gerçek para hareketini senkron tutar. Kısmi iade (örneğin üç üründen birinin iadesi) desteklenir; iyzico o ürünün ödeme kaleminden ilgili tutarı geri gönderir.

İade işlemlerinin izini kaybetmemek için sipariş ve iade kayıtlarını düzenli tutmanızı, ayrıca veritabanı yedeklerini almanızı öneririm. Basit bir kontrol sorgusuyla belirli bir tarih aralığındaki siparişleri hızlıca gözden geçirebilirsiniz:

-- Son 30 günün tamamlanan WooCommerce siparişleri (HPOS öncesi şema örneği)
SELECT p.ID           AS siparis_no,
       p.post_status  AS durum,
       p.post_date    AS tarih
FROM   wp_posts p
WHERE  p.post_type = 'shop_order'
  AND  p.post_status IN ('wc-processing', 'wc-completed', 'wc-refunded')
  AND  p.post_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
ORDER  BY p.post_date DESC;

Not: WooCommerce'in yeni sürümlerinde siparişler "High-Performance Order Storage (HPOS)" ile ayrı tablolarda tutulabilir; bu durumda sorgu wc_orders tablosuna göre değişir. Hangi şemayı kullandığınızı WooCommerce ayarlarından teyit edin.

İptal ve iade işlemlerinin çoğunu iyzico merchant panelinden de yapabilirsiniz; ancak mümkün olduğunca WooCommerce üzerinden yürütmek, mağaza tarafındaki sipariş durumuyla ödeme kuruluşundaki kaydın tutarlı kalmasını sağlar. İki tarafın birbirini tutmadığı durumlar, muhasebe ve müşteri iletişimi açısından baş ağrıtır.

Sık Karşılaşılan Sorunlar ve Bakım#

Entegrasyon çalışmaya başladıktan sonra en çok karşılaşılan sorunların başında "ödeme yöntemi checkout'ta görünmüyor" gelir. Bunun tipik nedenleri SSL eksikliği, mağaza para biriminin TRY olmaması veya ödeme yönteminin etkin olmamasıdır. İkinci sırada "3-D Secure sonrası siparişin processing'e geçmemesi" vardır; bu genelde dönüş (callback) URL'sinin dışarıdan erişilememesinden veya X-Forwarded-Proto başlığının eksikliğinden kaynaklanır.

Ödeme altyapısı, sitenizin gelir ürettiği en kritik bileşendir; bu yüzden bakımını ihmal etmeyin. WooCommerce, iyzico eklentisi ve WordPress çekirdeğini güncel tutun; her güncelleme öncesi bir yedek alın. Bu bakım döngüsünü kendiniz yönetmek istemiyorsanız WordPress bakım hizmetimizle güncelleme ve izlemeyi devredebilirsiniz. Ödeme trafiği arttıkça performansı da gözden kaçırmayın; yavaş bir checkout, terk edilen sepet demektir ve organik trafiği büyütürken bu kaybı SEO tarafındaki kazanımlarınızla telafi etmek zorlaşır.

Sıkça Sorulan Sorular#

iyzico entegrasyonu için SSL sertifikası zorunlu mu?#

Evet, kesinlikle zorunludur. Ödeme sayfasında kart bilgisi girilir ve 3-D Secure için banka sayfasına yönlendirme yapılır; bu akışın güvenli olabilmesi için sitenizin baştan sona HTTPS üzerinden çalışması gerekir. SSL olmadan tarayıcılar güvenlik uyarısı gösterir ve iyzico canlı modda genellikle bağlantıyı reddeder. Sertifikanız yoksa SSL sayfamızdan uygun bir sertifika edinebilirsiniz.

Kart bilgileri benim sunucumda saklanıyor mu, PCI uyumlu olmam gerekir mi?#

Hayır, iyzico'nun WooCommerce eklentisi tokenizasyon ve barındırılan (hosted) yaklaşım kullandığı için ham kart numaraları sizin sunucunuzda tutulmaz veya işlenmez. Bu sayede PCI DSS'in en ağır seviyesinden büyük ölçüde muaf olur, genellikle en basit öz-değerlendirme kapsamında kalırsınız. Yine de SSL, güncellemeler ve genel sunucu güvenliği sizin sorumluluğunuzdadır.

Test modunda gerçek para harcar mıyım?#

Hayır, sandbox (test) ortamında hiçbir gerçek para hareketi olmaz. iyzico'nun sağladığı sahte test kartlarıyla başarılı ödeme, reddedilen ödeme ve 3-D Secure iptali gibi senaryoları güvenle deneyebilirsiniz. Canlıya geçmeden önce en az bir başarılı ve bir başarısız akışı test etmenizi öneririm.

API ve Secret anahtarlarımı yanlışlıkla paylaşırsam ne olur?#

Bu anahtarlar mağazanızın kimliğidir ve sızması durumunda kötü niyetli kişiler adınıza işlem başlatmayı deneyebilir. Böyle bir şüphe varsa vakit kaybetmeden iyzico merchant panelinden anahtarları yeniden üretip WooCommerce eklentisindeki değerleri güncelleyin. Anahtarları asla kod deposuna, ekran görüntüsüne veya herkese açık dosyalara koymayın.

Taksit seçenekleri neden ödeme ekranında görünmüyor?#

En sık neden, iyzico merchant panelindeki taksit tanımları ile eklentinin gösterdiği taksit ayarlarının uyuşmamasıdır. Panelde ilgili bankalar için taksit ve komisyonun tanımlı olduğundan, mağaza para biriminin TRY olduğundan ve sepet tutarının minimum taksit eşiğini geçtiğinden emin olun. Bazı banka kartları (debit) taksit desteklemez; bu normaldir.

iade ile iptal arasındaki fark nedir?#

İptal, aynı gün içinde ve gün sonu kapanmadan önce yapılan, tutarın hiç tahsil edilmemiş gibi geri alındığı işlemdir. İade ise gün sonu kapandıktan sonra, tahsil edilmiş bir tutarın tamamının veya bir kısmının müşteriye geri gönderilmesidir. WooCommerce'te her ikisini de sipariş ekranından yürütebilir, kısmi iade yapabilirsiniz.

Kapanış#

WooCommerce ile iyzico entegrasyonu, doğru sırayla ilerlendiğinde teknik olarak zorlu bir iş değildir: önce SSL ve hosting altyapısını hazırlayıp, ardından sandbox anahtarlarıyla test edip, mutlu ve mutsuz senaryoları doğruladıktan sonra canlıya geçmek yeterlidir. Kritik olan; 3-D Secure'ü zorunlu tutmak, anahtarları güvende saklamak ve iade akışını canlıda gerçekten sınamaktır. Bu üçünü ihmal etmezseniz mağazanız, Türk müşterisinin güvenle kart girip taksitle alışveriş yapabileceği sağlam bir ödeme akışına kavuşur.

Bu entegrasyonun sağlam çalışması, altındaki barındırmanın kalitesine bağlıdır. Hızlı ve güvenli bir ödeme deneyimi için WordPress hosting paketlerimize göz atabilir, büyüyen trafiğe hazırlanmak için sanal sunucu çözümlerimizi değerlendirebilir, güncelleme ve izleme yükünü devretmek için WordPress bakım hizmetimizden faydalanabilirsiniz. Verilerinizi güvence altına almak içinse yedekleme ve SSL seçeneklerimiz her zaman yanınızda. Mağazanızı bugün doğru altyapıyla kurun, tahsilatı yarına bırakmayın.