iyzico Integration

iyzico is Türkiye'nin standart ödeme gateway'i — Turkish banking rails, BKM kartları, Troy desteği, 3D Secure tamam. For TRY (Turkish Lira) payments, iyzico is the right default; Stripe either doesn't support TRY in your region or routes through unfavorable FX. jekcms automatically routes to iyzico when the cart currency is TRY and falls back to Stripe for everything else.

Bu sayfa full entegrasyonu anlatıyor: API anahtarlarını almak, 3D Secure akışını ayarlamak, sandbox testleri ve canlıya geçiş.

API anahtarlarını almak

Sandbox (test mode)

1. [sandbox-merchant.iyzipay.com](https://sandbox-merchant.iyzipay.com) → sign up (herkese açık, KYC istemez)
2. Login → Ayarlar → API Anahtarları
3. Kopyala:

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

Production (live mode)

1. [merchant.iyzipay.com](https://merchant.iyzipay.com) → üye işyeri başvurusu
2. KYC sürecini tamamla — vergi levhası, imza sirküleri, IBAN, ticari evraklar yüklenir
3. iyzico onayından sonra (genellikle 2-5 iş günü) live API keys açılır
4. Ayarlar → API Anahtarları → live key'leri kopyala

jekcms'e anahtarları ekleme

1. Admin → Settings → Payment Settings
2. Scroll to the iyzico section
3. Paste:

- API Key → sandbox or live API key - Secret Key → matching secret

1. Base URL:

- Test: https://sandbox-api.iyzipay.com - Live: https://api.iyzipay.com

1. Leave Test mode ON for sandbox
2. Save

Keys are encrypted at rest. Swap the pair and flip test mode OFF when you go live.

Callback and webhook endpoints

iyzico 3D Secure iki endpoint kullanır:

3D Secure callback

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

Bu endpoint 3D doğrulamasından sonra browser redirect ile çağrılır. Kullanıcı bankanın 3D şifresini girer → banka iyzico'ya sonucu döner → iyzico kullanıcıyı buraya yönlendirir. jekcms callback.php içinde conversation token'ı doğrular ve kullanıcıyı order sonuç sayfasına yönlendirir.

iyzico panelinden ayarlanacak bir şey yok — callback URL her create request'inde runtime'da iletilir.

Webhook (async notification)

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

Async event bildirimi için (iade, chargeback, delayed auth). iyzico paneli → Ayarlar → Webhook → bu URL'i ekleyin, destekli event'leri seçin:

• PAYMENT_APPROVED
• PAYMENT_REFUND
• PAYMENT_CHARGEBACK
• PAYMENT_PENDING_AUTHORIZATION

Signature doğrulama

İki endpoint de HMAC-SHA256 signature doğrular. iyzico request body'si + secret key → hash. callback.php ve webhook.php içindeki IyzicoService::verifySignature() mismatch'te isteği reddeder (403). Secret key doğru olduğu sürece bu otomatik.

Zorunlu alanlar — iyzico API spesifikasyonu

Stripe'ın aksine iyzico checkout'ta buyer ve billing address alanlarını zorunlu tutar. customer/checkout.php TRY seçildiğinde genişleyen bir form render eder:

Buyer:

• Ad, soyad
• T.C. kimlik / VKN (11 hane bireysel, 10 hane kurumsal)
• GSM numarası (+90...)
• Email
• Kayıt tarihi, IP

Billing address:

• Ülke, şehir, ilçe
• Açık adres
• ZIP code

Shipping address:

• Digital ürünlerde buyer address ile aynı olabilir, ama field set'i aynı

Eksik field varsa iyzico API 5088 - Buyer information is missing döner ve ödeme başlamaz. jekcms form client-side'da bu alanları zorunlu yapar.

customer/checkout.php entegrasyonu

Akış:

1. Kullanıcı sepetini onaylar → customer/checkout.php
2. Sepet para birimi TRY ise jekcms iyzico'ya yönlendirir (USD/EUR/GBP → Stripe)
3. checkout.php bir conversation ID üretir, iyzico'ya threedsInitialize request'i atar
4. iyzico HTML form + content döner → jekcms browser'a yazdırır → banka 3D sayfasına otomatik submit
5. Kullanıcı 3D şifresini girer → banka → iyzico → api/payment/callback.php (redirect)
6. callback.php threedsPayment/auth ile ödemeyi finalize eder
7. Success → order paid işaretlenir, license issue, email gider
8. Webhook async olarak fulfillment'ı pekiştirir (async refund/chargeback için de aynı endpoint)

Test kartları (sandbox)

iyzico sandbox için official 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ı senaryosu | | Non-3D success | 5528 7900 0000 0008 | 12/30 | 123 | 3D olmadan approve | | Fraud reject | 4766 6200 0000 0007 | 12/30 | 123 | Fraud check fail |

3D şifre prompt'unda sandbox'ta herhangi bir string kabul edilir — banka sayfası her şeyi başarılı 3D olarak döner (senaryo karta bağlı).

Full liste iyzico docs altında: [iyzico test cards](https://docs.iyzico.com/test-cards).

Canlıya geçiş

1. KYC tamamla — merchant.iyzipay.com → evrakları yükle, onay bekle (2-5 iş günü)
2. Live API keys'i kopyala — production panelden
3. jekcms'te güncelle — sandbox keys'in üzerine yaz, Base URL'i https://api.iyzipay.com yap, Test mode OFF
4. Production webhook'u kaydet — live merchant panelde aynı URL'i ekle (sandbox webhook live'da çalışmaz)
5. Küçük bir live satış yap (1 TRY test license) — end-to-end doğrula

Troubleshooting

"Signature does not match". Secret key yanlış yapıştırılmış veya sandbox/live karışmış. Base URL ile key seti mutlaka aynı environment'tan olmalı.

5088 Buyer information is missing. Checkout form'da T.C./VKN veya GSM boş geçilmiş. Browser dev tools'ta payload'ı kontrol edin.

3D sayfasından geri dönmüyor. Callback URL HTTPS değilse iyzico redirect etmez. Sandbox'ta bile HTTP çalışmaz — local dev için ngrok kullanın.

Webhook gelmiyor. iyzico live panel → Webhook → Loglar → delivery attempt'lerine bak. 5xx dönüyorsa jekcms error log'a bak; 404 dönüyorsa URL slug yanlış.