iyzico Entegrasyonu Nasıl Yapılır? PHP ile Adım Adım

Türkiye'de online ödeme almak isteyen her işletmenin karşısına çıkan ilk isim iyzico'dur. Güçlü altyapısı, taksit ve 3D Secure desteğiyle en çok tercih edilen yerli ödeme sağlayıcılarından biridir. Bu rehberde iyzico entegrasyonunu bir PHP projesine nasıl ekleyeceğinizi baştan sona, pratik örneklerle anlatıyoruz.

iyzico Nedir ve Neden Tercih Edilir?

iyzico, işletmelerin web sitelerinde ve mobil uygulamalarında kredi kartıyla ödeme almasını sağlayan bir ödeme kuruluşudur. Kart bilgileri sizin sunucunuzda saklanmaz; bu da PCI-DSS yükünü büyük ölçüde azaltır ve güvenliği artırır. Ayrıca dolandırıcılık önleme sistemleri ile hem sizi hem müşterinizi korur.

Öne çıkan özellikler

• Taksit desteği: Müşteriye taksit seçeneği sunarak dönüşümü artırır.
• 3D Secure: Sahtekârlığa karşı ek güvenlik katmanı.
• Kolay entegrasyon: Hazır SDK ve API ile hızlı kurulum.
• Test ortamı (sandbox): Canlıya geçmeden her şeyi deneyebilirsiniz.
• Farklı entegrasyon seçenekleri: Checkout Form, API ve hazır butonlar.

Adım 1: iyzico Hesabı ve API Anahtarları

Önce iyzico'da bir işletme hesabı açın. Bu süreçte vergi bilgileriniz ve işletme belgeleriniz istenir. Onay sürecinden sonra panelden API Key ve Secret Key bilgilerinizi alırsınız. Geliştirme sırasında sandbox anahtarlarını, canlıya geçtiğinizde ise gerçek anahtarları kullanırsınız. Bu anahtarları asla herkese açık bir yerde (örneğin JavaScript içinde) saklamayın.

Adım 2: SDK Kurulumu

iyzico'nun resmi PHP SDK'sını Composer ile projenize ekleyin:

• `composer require iyzico/iyzipay-php`

Composer kullanamıyorsanız (bazı paylaşımlı hostinglerde), SDK klasörünü manuel olarak yükleyip dahil edebilirsiniz. SDK, API isteklerini hazırlamayı ve imzalamayı sizin yerinize yaptığı için entegrasyonu büyük ölçüde kolaylaştırır.

Adım 3: Ödeme İsteği Oluşturma

En yaygın yöntem Checkout Form akışıdır. Bu yöntemde iyzico size hazır bir ödeme sayfası sunar; kart bilgileri doğrudan iyzico'da işlenir, yani sizin sunucunuza hiç uğramaz. Akış şöyledir:

• Sipariş bilgilerini (tutar, ürün, alıcı bilgileri) hazırlayın.
• iyzico'ya bir CheckoutFormInitialize isteği gönderin.
• Dönen ödeme sayfası bağlantısına kullanıcıyı yönlendirin.
• Müşteri kart bilgilerini iyzico'nun güvenli sayfasında girer.

Callback (geri dönüş) yönetimi

Ödeme tamamlandığında iyzico, belirttiğiniz callback URL'ine bir istek gönderir. Bu adımda ödemeyi doğrulamak için CheckoutFormRetrieve çağrısı yaparsınız. Ödeme başarılıysa siparişi "ödendi" olarak işaretler ve ürünü teslim edersiniz. Callback URL'nizin HTTPS olması ve dışarıdan erişilebilir olması şarttır.

Adım 4: Ödeme Doğrulama ve Güvenlik

Callback'ten gelen veriye asla doğrudan güvenmeyin. Her zaman iyzico API'sine tekrar sorarak ödemenin gerçekten başarılı olduğunu doğrulayın. Bu, sahte istekleri ve manipülasyonu engeller. Ayrıca aynı ödemenin iki kez işlenmemesi için idempotent (tekrar-güvenli) bir kontrol ekleyin; müşteri sayfayı yenilerse ürün iki kez teslim edilmemelidir.

Bir diğer önemli nokta, ödeme tutarını da doğrulamaktır. Callback'te dönen tutarın, sipariş tutarıyla eşleştiğini kontrol edin; böylece istemci tarafında yapılan manipülasyonların önüne geçersiniz.

Adım 5: Test Ortamından Canlıya Geçiş

Sandbox ortamında her şeyi test edin: başarılı ödeme, başarısız ödeme, iptal ve iade senaryoları. iyzico, test için sahte kart numaraları sağlar. Her şey sorunsuz çalıştığında `.env` dosyanızdaki `IYZICO_BASE_URL` değerini canlı adresle değiştirin ve gerçek anahtarları girin.

• Sandbox: `https://sandbox-api.iyzipay.com`
• Canlı: `https://api.iyzipay.com`

Hazır Çözümle Zaman Kazanın

Sıfırdan entegrasyon, PHP ve API bilgisi gerektirir. Zamandan tasarruf etmek isterseniz, hazır iyzico ödeme eklentimiz taksit ve 3D Secure desteğiyle birlikte gelir. Dosyaları yükleyip anahtarlarınızı girmeniz yeterlidir; entegrasyon dakikalar içinde tamamlanır ve callback yönetimi hazır gelir.

Taksit, İade ve Raporlama

iyzico entegrasyonunun sunduğu değer, tek seferlik ödeme almanın ötesine geçer. Taksit özelliği, özellikle yüksek fiyatlı ürünlerde dönüşümü belirgin biçimde artırır; müşteriye ödeme kolaylığı sunmak, satın alma kararını hızlandırır. Taksit oranlarını ve komisyon dağılımını iyzico panelinden yönetebilirsiniz.

İade işlemleri de entegrasyonun bir parçası olmalıdır. Bir müşteri iade talep ettiğinde, iyzico API'si üzerinden kısmi veya tam iade yapabilirsiniz. Bu sürecin sipariş yönetim sisteminizle entegre olması, muhasebenizi düzenli tutar.

Son olarak iyzico paneli, satışlarınızı, işlem ücretlerinizi ve ödeme aktarımlarınızı raporlar. Bu verileri düzenli takip etmek, nakit akışınızı yönetmenize ve büyümenizi ölçmenize yardımcı olur. İyi bir entegrasyon, yalnızca ödeme almaz; işinizin finansal röntgenini de çeker.

Sık Karşılaşılan Sorunlar

"Signature" hatası: API ve Secret anahtarlarının doğru ve boşluksuz girildiğinden emin olun. Callback çalışmıyor: URL'nin HTTPS olduğundan ve dışarıdan erişilebilir olduğundan emin olun. Taksit görünmüyor: iyzico panelinden taksit ayarlarınızı kontrol edin. Ödeme başarılı ama sipariş güncellenmiyor: Callback doğrulama kodunuzu ve veritabanı güncellemenizi kontrol edin. Test kartıyla gerçek para çekilir mi? Hayır, sandbox ortamındaki test kartlarıyla gerçek tahsilat yapılmaz; yalnızca akışı denemenizi sağlar. Yurt dışı kart kabul edebilir miyim? iyzico çoğu uluslararası kartı destekler; ancak ayarlarınızdan bunu etkinleştirdiğinizden emin olun. Komisyon oranları nedir? Oranlar işlem hacminize ve anlaşmanıza göre değişir; güncel bilgiyi iyzico panelinden görebilirsiniz.

Sonuç

iyzico entegrasyonu, doğru adımlarla ilerlediğinizde birkaç saatlik bir iştir. Sandbox'ta test etmeden canlıya geçmeyin ve ödeme doğrulamasını her zaman sunucu tarafında yapın. Unutmayın ki ödeme akışı, müşterinin sizinle kurduğu en hassas temas noktasıdır; burada yaşanan en küçük bir sorun bile satışın kaybedilmesine yol açar. Bu yüzden ödeme sayfanızın hızlı açılması, güven veren bir tasarıma sahip olması ve hata durumlarında müşteriye net bir mesaj göstermesi kritik önemdedir. Ödeme altyapınızı hızlıca ve güvenli biçimde kurmak için eklenti kategorimizi inceleyebilir, projenize en uygun çözümü seçebilirsiniz. Güvenli ve sorunsuz bir ödeme deneyimi, müşteri güveninin ve tekrarlayan satışların temelidir.