iyzico Entegrasyonu

iyzico, Türkiye'nin standart ödeme gateway'i. Türk bankacılık altyapısına bağlı, BKM kartları ve Troy destekli, 3D Secure'lü. Sitenizde Türk Lirası ile ödeme alacaksanız iyzico doğru seçim — Stripe ya TRY'yi bölgenizde kabul etmiyor ya da elverişsiz kurlardan çevirerek alıyor. jekcms, sepet para birimi TRY olduğunda otomatik olarak iyzico'ya yönlendiriyor, geri kalan her şey için Stripe'a düşüyor.

Bu sayfa her şeyi baştan sona anlatıyor: anahtarları nereden alacağınız, 3D Secure akışının nasıl kurulduğu, sandbox'ta nasıl test edeceğiniz, canlıya nasıl geçeceğiniz.

API anahtarlarını alma

Sandbox (test) modu

sandbox-merchant.iyzipay.com → kayıt olun (herkese açık, KYC evrakı istemez)
Giriş yapın → Ayarlar → API Anahtarları
Kopyalayın:

- API Key (public identifier) - Secret Key (signing secret)

Production (canlı) modu

merchant.iyzipay.com → üye işyeri başvurusunda bulunun
KYC sürecini tamamlayın — vergi levhası, imza sirküleri, IBAN, ticari evrakları yüklersiniz
iyzico onayı gelince (genelde 2-5 iş günü) live API anahtarları açılır
Ayarlar → API Anahtarları → live anahtarları kopyalayın

Anahtarları jekcms'e eklemek

Admin → Settings → Payment Settings
iyzico bölümüne gelin
Yapıştırın:

- API Key → sandbox veya live API anahtarı - Secret Key → eşleşen secret

Base URL:

- Test için: https://sandbox-api.iyzipay.com - Live için: https://api.iyzipay.com

Sandbox'tayken Test mode'u ON bırakın
Kaydedin

Anahtarlar veritabanında şifrelenmiş saklanır. Canlıya geçerken anahtar çiftini değiştirip Test mode'u OFF yapacaksınız — ayrıca Base URL'yi de live olanla güncellemeyi unutmayın.

Callback ve webhook nedir?

iyzico 3D Secure için iki ayrı uç nokta kullanır. Karıştırmayın.

3D Secure callback

https://yourdomain.com/api/payment/callback.php

Bu, kullanıcının bankadan 3D şifresini girdikten sonra tarayıcı yönlendirmesiyle gelen uç noktadır. Akış şöyle: kullanıcı banka sayfasında şifreyi giriyor → banka iyzico'ya "doğrulandı" diyor → iyzico kullanıcıyı bu URL'ye yönlendiriyor. callback.php conversation token'ı doğruluyor ve kullanıcıyı sonuç sayfasına götürüyor.

iyzico panelinde ayrıca ayarlamanıza gerek yok — callback URL her create isteğinde anlık olarak gönderiliyor.

Webhook (asenkron bildirim)

https://yourdomain.com/api/payment/webhook.php

Bu ise sonradan gelen olay bildirimleri için: iade, chargeback, gecikmeli yetkilendirme gibi durumlar. iyzico panelinde → Ayarlar → Webhook → bu URL'yi eklersiniz ve şu olayları seçersiniz:

PAYMENT_APPROVED
PAYMENT_REFUND
PAYMENT_CHARGEBACK
PAYMENT_PENDING_AUTHORIZATION

İmza doğrulama

iki uç nokta da HMAC-SHA256 imzasını kontrol eder. iyzico istek gövdesi + secret key ile hash üretir; jekcms IyzicoService::verifySignature() ile bunu doğrular. Eşleşmezse 403 döner. Secret key doğru yapıştırıldığı sürece bu otomatik çalışır.

Zorunlu alanlar — iyzico'nun istekli olduğu bilgiler

Stripe'tan farklı olarak iyzico checkout'ta alıcı ve fatura adresi alanlarını zorunlu tutar. Kullanıcı TRY ile ödeme yapmayı seçtiğinde customer/checkout.php genişleyip bu alanları ister:

Alıcı bilgileri:

Ad, soyad
T.C. kimlik numarası (bireyselse 11 hane) ya da VKN (kurumsalsa 10 hane)
GSM numarası (+90... biçiminde)
E-posta
Kayıt tarihi ve IP

Fatura adresi:

Ülke, şehir, ilçe
Açık adres
Posta kodu

Teslimat adresi:

Dijital üründe alıcı adresiyle aynı olabilir, ama alan seti aynı doldurulmalı

Herhangi bir alan eksik olursa iyzico API 5088 - Buyer information is missing hatası döner ve ödeme hiç başlamaz. jekcms formu bu alanları istemci tarafında zorunlu kılar.

Ödeme akışı — adım adım

Kullanıcı sepeti onaylar → customer/checkout.php açılır
Sepet para birimi TRY ise jekcms otomatik iyzico'ya yönlenir (USD/EUR/GBP → Stripe)
checkout.php benzersiz bir conversation ID üretir, iyzico'ya threedsInitialize isteği gönderir
iyzico bir HTML form ve içerik döner → jekcms tarayıcıya yazar → otomatik olarak bankanın 3D sayfasına submit edilir
Kullanıcı banka sayfasında 3D şifresini girer → banka → iyzico → api/payment/callback.php (tarayıcı yönlendirmesi)
callback.php, threedsPayment/auth çağrısıyla ödemeyi sonlandırır
Başarılıysa → sipariş paid işaretlenir, lisans çıkar, e-posta gider
Webhook asenkron olarak karşılamayı pekiştirir (iade/chargeback olayları da aynı uç noktadan gelir)

Sandbox test kartları

iyzico'nun resmi test kartları:

| Kart | Numara | Son Kullanma | CVV | Senaryo | |---|---|---|---|---| | Halkbank | 5890 0400 0000 0016 | 12/30 | 123 | Başarılı 3D | | İş Bankası | 4543 5909 0000 0006 | 12/30 | 123 | Başarılı 3D | | Garanti | 5526 0800 0000 0006 | 12/30 | 123 | 3D şifre hatası | | Non-3D success | 5528 7900 0000 0008 | 12/30 | 123 | 3D'siz direkt onay | | Fraud reject | 4766 6200 0000 0007 | 12/30 | 123 | Fraud check başarısız |

3D şifre ekranında sandbox'ta herhangi bir şey yazabilirsiniz — senaryoyu kartın kendisi belirler. Tam liste için: iyzico test cards.

Canlıya geçiş

KYC tamamlayın — merchant.iyzipay.com'da evrakları yükleyin, onay bekleyin (2-5 iş günü)
Live API anahtarlarını production panelden kopyalayın
jekcms'te güncelleyin — sandbox anahtarlarının üzerine yazın, Base URL'yi https://api.iyzipay.com yapın, Test mode OFF
Production webhook'u kaydedin — live merchant panelde aynı webhook URL'sini ekleyin. Sandbox webhook live'da çalışmaz, ayrı kaydetmeniz gerekir
Küçük bir canlı işlem deneyin (1 TRY'lik test lisansı) — uçtan uca doğrulayın

Sorun giderme

"Signature does not match" — Secret key yanlış yapıştırılmış olabilir, ya da sandbox/live karışmış. Base URL ile API anahtarı aynı ortamdan olmak zorunda.

5088 Buyer information is missing — Checkout formunda T.C./VKN veya GSM boş geçilmiş. Tarayıcı dev tools'ta gönderilen payload'ı açıp kontrol edin.

3D sayfasından geri dönmüyor — Callback URL HTTPS değilse iyzico yönlendirme yapmaz. Sandbox'ta bile HTTP çalışmaz. Yerel geliştirmede ngrok gibi bir tünel kullanın.

Webhook gelmiyor — iyzico live panel → Webhook → Loglar → teslim denemelerine bakın. 5xx dönüyorsa jekcms error log'una göz atın, 404 dönüyorsa URL slug yanlış yazılmıştır.