iyzico

Bu rehberde: iyzico hesabınızı API anahtarı ve güvenlik anahtarıyla bağlarsınız. Başarılı her ödeme, iyzico'nun üye işyeri bildirimi üzerinden bir iş akışı başlatır (teşekkür mesajı, değerlendirme isteği, WhatsApp takibi). Akış içinden ödeme okuyabilir ve müşteriye gönderilecek ödeme linki oluşturabilirsiniz.

⏱ 15 dakika

Kimlik kartı#

Ne işe yarar?#

Tetikleyici: Payment succeeded – ödeme formu (checkout form), API, iyzico ile Öde ve link ödemeleri başarılı olduğunda iyzico bildirim adresinize istek gönderir. OrqLabs imzayı doğrular, ödemeyi iyzico API'sinden yeniden okur ve akışı şu alanlarla başlatır:

paymentId, status (SUCCESS), total (tahsil edilen tutar, paidPrice), price (sepet tutarı), currency, installment, conversationId, basketId, token (ödeme formu ödemelerinde), eventType (CHECKOUT_FORM_AUTH, API_AUTH …), items (name = sepet kalemi kimliği, quantity, price), cardAssociation, lastFourDigits, fraudStatus, createdAt, raw.

Önemli: iyzico bildirimleri ve ödeme sorgusu alıcının adını, e-postasını veya telefonunu içermez. Teşekkür mesajı göndermek için ödemeyi kendi sipariş kaydınızla conversationId veya basketId üzerinden eşleştirin (ör. HTTP isteği kutusuyla sitenizin sipariş API'sinden, Google Sheets'ten veya mağaza entegrasyonunuzdan – Shopify, WooCommerce, ikas – müşteri bilgisini alın). Mağazanız bu entegrasyonlardan biriyse "sipariş ödendi" olayını doğrudan o mağazadan dinlemek çoğu zaman daha pratiktir.

iyzico kutusunun işlemleri:

Editördeki test çalıştırmalarında ödeme linki oluşturulmaz; kutu ne yapacağını çıktıya yazar. Get payment çalışır.

Ön koşullar#

• Onaylı bir iyzico üye işyeri hesabı (deneme için sandbox-merchant.iyzipay.com üzerinden ücretsiz sandbox hesabı).
• iyzico Link kullanacaksanız hesabınızda link ile ödemenin açık olması; hızlı link için iyzico'nun tutar sınırı geçerlidir (yazım tarihinde 750 TL).
• Ürün linki için herkese açık bir ürün görseli adresi (JPG/PNG, en fazla 5 MB) – iyzico görselsiz ürün linki kabul etmez.

Adım adım kurulum#

A) iyzico'da API anahtarları#

1. iyzico üye işyeri paneline girin (sandbox için sandbox paneline).
2. Ayarlar → Firma Ayarları sayfasında API Anahtarı ve Güvenlik Anahtarı (secret key) değerlerini kopyalayın.

B) OrqLabs'ta bağlama#

1. Entegrasyonlar → iyzico → Bağla → Proje seçin.
2. API anahtarı, Güvenlik anahtarı ve Ortam (Canlı / Sandbox) alanlarını doldurun → Bağla.
3. Entegrasyon kartına tıklayın; ayrıntı panelinde gösterilen webhook adresini kopyalayın. Biçimi: https://<api-adresi>/api/v1/webhooks/iyzico/<entegrasyon-kimliği>.

C) iyzico panelinde bildirim adresi#

1. iyzico panelinde Ayarlar → Firma Ayarları → Üye İşyeri Bildirimleri (Merchant Notifications) bölümünü açın.
2. Bildirim adresi (webhook URL) olarak OrqLabs'tan kopyaladığınız adresi yapıştırın (HTTPS zorunlu) ve bildirimleri etkinleştirin → Kaydet.
3. Sandbox'ta bir test ödemesi yapın (iyzico test kartları); birkaç saniye sonra iş akışının Çalıştırmalar sekmesinde yeni bir çalıştırma görmelisiniz.

iyzico hesabınızda tek bir bildirim adresi tanımlanabilir. Kendi siteniz bu adresi zaten kullanıyorsa sitenizden gelen isteği gövdesi ve X-IYZ-SIGNATURE-V3 başlığıyla birlikte değiştirmeden OrqLabs adresine iletin (forward) veya OrqLabs adresini kullanıp siparişinizi akıştan güncelleyin.

Örnek iş akışları#

1) Ödeme sonrası teşekkür ve WhatsApp takibi#

1. Entegrasyon olayı – IYZICO · Payment succeeded.
2. HTTP isteği – sitenizin sipariş API'sinden {{ $json.conversationId }} numaralı siparişi (müşteri adı, telefon) alın.
3. Metin üret – {{ $json.customerName }} adlı müşterimize {{ $node["Entegrasyon olayı"].json.total }} TL'lik ödemesi için kısa bir teşekkür mesajı yaz.
4. Mesaj gönder – WhatsApp, alıcı {{ $node["HTTP isteği"].json.phone }}, onaylı şablonla (sipariş bildirimi pencere dışı bir mesajdır).

2) Teslimattan sonra değerlendirme isteği#

Entegrasyon olayı (IYZICO · Payment succeeded) → müşteri bilgisini alan HTTP isteği → Bekle (5 gün) → E-posta gönder ("Ürününüzü nasıl buldunuz?" + değerlendirme bağlantısı).

3) Sohbetten ödeme linki#

Sohbet botu veya Gelen Kutusu akışında iyzico → Create payment link (Link type Fast link, Description Kapora – {{ $json.name }}, Price {{ $json.amount }}) → Mesaj gönder (Ödemenizi bu bağlantıdan yapabilirsiniz: {{ $json.url }}).

İYS ve izin: Teşekkür ve sipariş bilgilendirmesi gibi işlemsel mesajlar ticari ileti sayılmaz. Değerlendirme isteğine kampanya, indirim kodu veya yeni ürün tanıtımı eklerseniz mesaj ticari elektronik ileti olur: Türkiye'de tüketicilere göndermeden önce alıcının onayı alınmış ve İYS'ye kaydedilmiş olmalıdır (İYS kutusunun Query consent işlemiyle akış içinde kontrol edebilirsiniz). WhatsApp'ta pencere dışı mesajlar için ayrıca Meta onaylı şablon gerekir.

Tetikleyici nasıl çalışır?#

• iyzico ilk bildirimi ödemeden 10–15 saniye sonra gönderir; 2xx yanıt alamazsa 15 dakikada bir, en fazla 3 kez yeniden dener.
• Her bildirim X-IYZ-SIGNATURE-V3 başlığıyla gelir: HMAC-SHA256(secretKey + iyziEventType + paymentId + paymentConversationId + status) (ödeme formunda iyziPaymentId + token ile), anahtar güvenlik anahtarınızdır. İmza tutmazsa istek reddedilir (401).
• İmzasız bildirimler reddedilir. İmzalı bildirimde ödeme ayrıca iyzico API'sinden yeniden okunur (/payment/detail). API ödemeyi SUCCESS göstermiyorsa veya sahtecilik kontrolü reddettiyse (fraudStatus = -1) akış başlamaz.
• İade ve bekleyen (PENDING / INIT) olaylar ile başarısız ödemeler akış başlatmaz. Aynı ödeme için tekrar gelen bildirimler ikinci kez akış başlatmaz.

Limitler#

Bağlantıyı test etme#

Bağlantıyı test et iyzico'ya imzalı bir BIN sorgusu gönderir; anahtarlar ve ortam doğruysa bağlantı başarılı görünür. Bildirim adresini denemek için sandbox ortamında test kartıyla bir ödeme yapın.

Kimlik bilgilerini yenileme#

iyzico panelinde anahtarları yenilerseniz OrqLabs'ta ayrıntı panelinden Kimlik bilgileri → Güncelle ile yeni API ve güvenlik anahtarını girin. Güvenlik anahtarı bildirim imzasında da kullanıldığı için eski anahtarla gelen bildirimler reddedilir.

Sık karşılaşılan hatalar#

Sonraki adım#

• PayTR
• Shopier
• Entegrasyonlara genel bakış