Özel Yazılıma Sanal POS Entegrasyonu (iyzico/PayTR): 3DS, Güvenli Webhook ve Mutabakat Rehberi

Özel bir yazılıma sanal POS entegrasyonu, çoğu ekibin sandığının aksine "iyzico'nun ya da PayTR'nin API'sini çağırmak"tan ibaret değildir. Üretime hazır bir entegrasyon dört ayrı problemi aynı anda çözmek zorundadır: (1) 3D Secure (3DS) akışını doğru kurmak — kullanıcıyı bankanın doğrulama ekranına gönderip geri almak; (2) callback/webhook'u güvenli doğrulamak — gelen bildirimin gerçekten sağlayıcıdan geldiğini imzayla ispatlamak, tekrarlı bildirimlere karşı idempotent olmak ve hızla 2xx dönmek; (3) ödeme ile siparişi mutabık kılmak — parayı tahsil ettiğiniz olayı doğru siparişe bağlamak; ve (4) iade/iptal/taksit gibi işlem sonrası senaryoları yönetmek. Bunlardan herhangi biri eksikse entegrasyon "çalışıyor" görünür ama üretimde para kaybettiren sessiz hatalara açıktır: iki kez işlenen sipariş, "ödendi" göründüğü hâlde onaylanmamış sepet ya da sahte bir callback ile bedava ürün. Bu yazıda Sakarya merkezli bir B2B / white-label yazılım firması olarak ürettiğimiz sanal POS entegrasyonlarında uyguladığımız çerçeveyi olduğu gibi paylaşıyoruz: banka sanal POS'u mu ödeme kuruluşu mu, hosted form mu direkt API mi, 3DS akışı, güvenli webhook, mutabakat, iade/taksit ve canlıya çıkış öncesi kontrol listesi.

Bu yazı, ödeme entegrasyonunu bir API entegrasyonu projesi ve bir e-ticaret altyapısı meselesi olarak ele alır. Aynı disiplini ERP/e-fatura tarafında da uyguladık; entegrasyonun "hazır mı özel mi" kararını merak ediyorsanız e-ticaret, ERP ve e-fatura entegrasyonu yazımıza bakabilirsiniz. Aşağıdaki teknik ayrıntılar iyzico ve PayTR'nin resmi dokümanlarına dayanır; her sağlayıcı zamanla değişebileceği için tek gerçek kaynak, entegrasyon anındaki resmi dokümantasyondur.

Banka sanal POS'u mu, ödeme kuruluşu mu?

İlk mimari karar, kart tahsilatını hangi kanaldan yapacağınızdır. Türkiye'de sanal POS iki şekilde sunulur: (a) doğrudan bir bankayla sözleşmeli banka sanal POS'u ve (b) bankadan bağımsız ödeme kuruluşları (iyzico, PayTR gibi). Ödeme kuruluşları, 6493 sayılı Ödeme ve Menkul Kıymet Mutabakat Sistemleri, Ödeme Hizmetleri ve Elektronik Para Kuruluşları Hakkında Kanun kapsamında faaliyet gösterir ve faaliyet izni BDDK'dan değil, TCMB'den alınır (Kanun md.12) (TCMB — Ödeme Kuruluşları).

Pratik fark şu: banka sanal POS'unda genellikle her banka için ayrı bir entegrasyon ve sözleşme gerekir; bağımsız ödeme kuruluşu ise tek entegrasyonla çoğu bankanın kartını kabul etmenizi sağlar. iyzico özellikle pazaryeri / alt üye işyeri (submerchant) senaryolarında öne çıkar. Karar kuralı basittir:

• Tek banka, yüksek hacim, en düşük komisyon önceliğiniz ise ve tek bir bankayla güçlü ilişkiniz varsa banka sanal POS'u mantıklı olabilir; ancak çoklu banka desteği isterseniz entegrasyon yükü katlanır.
• Hızlı canlıya çıkış, çoklu banka kabulü ve tek entegrasyon istiyorsanız ödeme kuruluşu (iyzico/PayTR) çoğu B2B ve KOBİ senaryosunda daha az bakım maliyeti getirir.
• Pazaryeri / komisyon paylaşımı / alt üye işyeri gerekiyorsa submerchant desteği olan bir ödeme kuruluşu neredeyse zorunludur.

Hosted form mu, direkt API mi? PCI-DSS kapsamı burada belirlenir

İkinci ve belki en kritik karar, kart verisinin nereden geçeceğidir — çünkü bu doğrudan PCI-DSS kapsamınızı belirler. İki yaklaşım vardır:

• Hosted / barındırılan ödeme formu: Kart bilgileri sağlayıcının barındırdığı bir sayfa veya iframe içinde toplanır. PayTR iFrame API'de kullanıcı kartını PayTR'nin iframe'i içinde girer; iyzico tarafında ise CheckoutForm, iyzico'nun barındırdığı ödeme sayfasıdır (CF-Initialize ile paymentPageUrl/token döner, iframe=true ile gömülebilir). Her iki durumda da hassas kart verisi sizin sunucunuza dokunmaz, dolayısıyla PCI-DSS kapsamınız önemli ölçüde daralır.
• Direkt API: Ödemeyi kendi ödeme formunuzla toplarsınız; kart verisi kendi altyapınızdan geçer. Bu, tam kontrol ve markalı bir deneyim sunar ama PCI-DSS yükümlülüğünüzü ciddi biçimde artırır.

Hem iyzico hem PayTR, sağlayıcı tarafında PCI korumasını üstlenir; iyzico kendini PCI DSS Level 1 hizmet sağlayıcısı olarak konumlandırır. Ancak şunu net söyleyelim: kesin SAQ tipiniz (SAQ A, SAQ A-EP vb.) entegrasyon detayına bağlıdır ve bu yazıda iddia edilmez; genel doğru olan, kart verisi sizin sunucunuza uğramadığında kapsamın azaldığıdır. Pratik tavsiyemiz nettir:

Markalı, tam kontrollü bir kasa deneyimine iş gereksiniminiz yoksa hosted formu seçin. Kazandığınız birkaç piksel özelleştirme, üstleneceğiniz PCI-DSS denetim ve sorumluluk yüküne değmez.

3DS akışı nasıl çalışır? (iyzico örneği)

3D Secure, kart sahibinin bankası tarafından yapılan ek doğrulamadır (tek kullanımlık kod, banka uygulaması onayı vb.). Bu adım kaçırılırsa chargeback riski ve sorumluluk büyük ölçüde işletmenin üstünde kalır. iyzico'da 3DS, iki adımlı bir POST akışıdır:

• Adım 1 — Init 3DS: /payment/3dsecure/initialize endpoint'ine kart/alıcı bilgileri ve bir callbackUrl ile POST atarsınız. Yanıtta base64 kodlu bir threeDSHtmlContent döner. Bu HTML render edilerek kullanıcı bankanın 3DS doğrulama ekranına yönlendirilir.
• Adım 2 — Auth 3DS: Kullanıcı bankada doğrulamayı tamamlayıp callbackUrl'inize döndükten sonra, Init'ten dönen paymentId ile ikinci bir POST'u auth endpoint'ine atarsınız. iyzico burada v2 endpoint kullanımını önerir (/payment/v2/3dsecure/auth, yani 3DS 2.0); legacy /payment/3dsecure/auth ise 3DS 1.0'dır.

Doğrulamanın sonucunu mdStatus alanı taşır: 1 başarılı, 0 ve 2–8 değerleri başarısız doğrulamayı ifade eder. Önemli bir uyarı: bankanın callbackUrl'inize gönderdiği POST gövdesinin tam alan şemasını burada kesin bir liste olarak vermiyoruz — çünkü bu, sürüme ve entegrasyona göre değişebilir; canlıya çıkmadan önce güncel resmi dokümandan doğrulanması gereken bir ayrıntıdır (iyzico — Init 3DS, iyzico — Auth 3DS).

Akış boyunca isteği yanıtla eşleştirmek için conversationId kullanılır. iyzico bunu "request/response correlation için benzersiz ID" olarak tanımlar; kendi sipariş numaranızı buraya koyabilirsiniz ve istekte gönderdiğiniz değer yanıtta aynen geri döner. Ayrı olarak iyzico her başarılı ödemeye kendi tarafında bir paymentId atar; iade ve iptal işlemleri bu paymentId üzerinden yürür.

Güvenli webhook/callback doğrulaması: imza, idempotency, hızlı 2xx

Bir ödeme entegrasyonunun en çok atlanan ve en tehlikeli kısmı budur. Callback/webhook, sunucudan sunucuya gelen ve parayı tahsil edildi olarak işaretleyeceğiniz asıl olaydır. Üç kural pazarlıksızdır: imza doğrula, idempotent ol, hızlı 2xx dön.

1) İmza doğrulama — bildirimin gerçekten sağlayıcıdan geldiğini ispatla

Callback'inize gelen her POST'u, imzasını doğrulamadan asla "ödendi" saymayın. Aksi hâlde bir saldırgan sahte bir "başarılı ödeme" bildirimi göndererek bedava sipariş açtırabilir. İki sağlayıcının mekanizması farklıdır:

• PayTR (iFrame API): notify_url'e gelen bildirimde hash, base64_encode(hash_hmac('sha256', merchant_oid + merchant_salt + status + total_amount, merchant_key, true)) ile hesaplanır. Gelen POST'taki hash bu değerle birebir eşleşmezse istek PayTR'den gelmemiş kabul edilip reddedilmelidir. Bu formül iFrame API içindir (dört alan); PayTR'nin diğer API'lerinde alan seti farklı olabilir, karıştırmayın.
• iyzico (webhook): Doğrulama X-IYZ-SIGNATURE-V3 header'ı ile HMAC-SHA256 (HEX) kullanılarak yapılır; eski header sürümleri artık desteklenmez. Kritik nokta: imza için birleştirilen alan sırası webhook tipine göre değişir. Direct payment, HPP ve subscription farklı parametre sıraları kullanır — tek bir "genel" webhook imza sırası yoktur; kendi entegrasyon tipinizin sırasını resmi tablodan doğrulayın.

iyzico ayrıca senkron API yanıtları için ayrı bir response signature mekanizması sunar: belirli parametreler iki nokta (:) ile birleştirilip secretKey ile HMAC-SHA256 hash'lenir ve HEX'e kodlanır; fiyatlardaki gereksiz sondaki sıfırlar temizlenir (10.50 → 10.5, 10.00 → 10). Parametre sırası endpoint'e göre değişir; örneğin non-3DS auth için sıra paymentId:currency:basketId:conversationId:paidPrice:price şeklindedir ve v2 3DS auth da aynı alan sırasını kullanır (iyzico — Response Signature Validation, iyzico — Webhook, PayTR — iFrame API 2. adım).

2) Idempotency — aynı bildirim iki kez gelirse iki kez işleme

Her iki sağlayıcı da aynı işlem için birden fazla bildirim gönderebilir. Sipariş kimliğiniz üzerinden tekilleştirme yapmazsanız, aynı sipariş iki kez onaylanır, iki kez stok düşer, iki kez kargo açılır. PayTR bunu açıkça belirtir: tekrar kontrolü benzersiz merchant_oid alanına göre yapılmalı; siparişi onaylamak/iptal etmek için yalnızca ilk bildirim işlenmeli, tekrar edenlere sadece yanıt dönülmelidir. Pratik uygulama: bildirimin durumunu (işlendi/işlenmedi) veritabanınızda sipariş kimliğine bağlı, tekil bir kayıtla tutun ve işlemeyi tek bir atomik işlem içinde yapın.

3) Hızlı 2xx dön — ağır işi asenkron yap

Sağlayıcı, bildirime kısa sürede olumlu bir yanıt bekler; alamazsa yeniden dener. iyzico webhook'ta merchant 2xx dönmezse 15 dakikada bir, en fazla 3 kez tekrar dener. PayTR ise "OK" alamazsa 1 dakika sonra tekrar dener ve yanıt gövdesinin — HTML ya da başka içerik olmadan — sadece düz metin OK olmasını ister. Buradan çıkan iki kural:

• Önce doğrula, sonra kaydet, sonra yanıtla: imzayı doğrulayın, siparişi tekil olarak işaretleyin, ardından beklenen yanıtı dönün. E-posta gönderme, fatura kesme, ERP'ye yazma gibi ağır işleri asenkron bir kuyruğa atın; bunları callback yanıtını bloklayacak biçimde senkron yapmayın.
• Yanıt gövdesini sağlayıcının beklediği formatta dönün: PayTR için tam olarak OK; iyzico için 2xx HTTP durum kodu. Aksi hâlde gereksiz retry'lar ve "kaybolmuş" ödemeler yaşarsınız.

Ödeme–sipariş mutabakatı (reconciliation)

Mutabakat, "sağlayıcının tahsil ettiği para" ile "sizin sisteminizdeki sipariş" arasındaki köprüdür. Zayıf kurulmuş bir mutabakat, muhasebe ve müşteri hizmetleri tarafında en çok baş ağrıtan kısımdır. İki sağlayıcının da bu köprüyü kurma yolu, merchant tarafından üretilen benzersiz bir sipariş kimliğidir:

• PayTR: merchant_oid (en fazla 64 alfanümerik karakter) işlem için belirlediğiniz benzersiz sipariş numarasıdır; callback'te size geri döndürülerek mutabakatı sağlar. Ayrıca 1. adımda paytr_token HMAC-SHA256 + base64 ile üretilir ve birleştirilen string merchant_id + user_ip + merchant_oid + email + payment_amount + user_basket + no_installment + max_installment + currency + test_mode + merchant_salt alanlarını içerir.
• iyzico: conversationId'yi kendi sipariş numaranız olarak kullanın; istekte gönderdiğiniz değer yanıtta aynen döner. Sağlayıcı tarafındaki karşılığı ise paymentId'dir — iade/iptal bunun üzerinden yapılır. İki kimliği de kendi sipariş kaydınızda saklayın.

Sağlam bir mutabakat için pratik ilkeler:

• Otoriteyi callback'e verin, tarayıcıya değil: Kullanıcının tarayıcısının döndüğü "başarı" sayfası bir ipucudur, kanıt değildir. Siparişi asıl olarak sunucudan sunucuya gelen ve imzası doğrulanan callback ile onaylayın.
• Tutar ve para birimini karşılaştırın: Callback'teki tutarı, siparişinizde beklenen tutarla eşleştirin; uyuşmuyorsa işlemeyin, alarma düşürün.
• Bekleyen (pending) durumları kapatın: Callback hiç gelmezse "ödeme başlatıldı ama sonuçlanmadı" siparişleri bir arka plan işiyle sağlayıcının sorgu API'sinden kontrol edip kapatın.
• Günlük mutabakat: Sağlayıcının işlem/ödeme raporlarını kendi kayıtlarınızla düzenli karşılaştırın; tek başına webhook'a güvenmeyin.

İade, kısmi iade ve taksit

Ödeme akışının ikinci yarısı işlem sonrası senaryolardır; müşteri deneyimi ve muhasebe doğruluğu burada kazanılır. iyzico özelinde temel ayrımlar:

• İade (refund) — tam veya kısmi: İki yol vardır. /payment/refund kalem bazında çalışır (paymentTransactionId yani sepet kaleminin işlem kırılımı ID'si ve price ile). /v2/payment/refund ise ödeme bazında çalışır (paymentId ve price ile); iade edilecek sepet kalemini sistem kendisi belirler. Her iki sürüm de tam/kısmi iadeyi destekler ve banka referansı (refundHostReference, authCode) döndürür.
• İptal (cancel): /payment/cancel yalnızca paymentId ile çağrılır, kısmi tutarı desteklemez ve ödemenin tamamını iptal eder. iyzico dokümanına göre cancel işlemi ödeme ile aynı gün yapılabilir ve kart ekstresinde giriş/çıkış kaydı oluşturmaz; iade (refund) ise ekstreye yansır ve bankaya göre birkaç gün sürebilir. Kesin gün/saat kapanış kuralları bankaya ve valöre göre değişir; bunu genel bir ilke olarak alın, kesin muhasebe kuralı olarak değil.
• Taksit ve BIN sorgusu: POST /payment/iyzipos/installment ile price (zorunlu) ve opsiyonel binNumber (8 haneli BIN) göndererek taksit seçeneklerini, oranlarını ve tutarlarını, ayrıca kart ailesi/şeması ve banka bilgisini sorgulayabilirsiniz. Yalnızca tutarla (BIN olmadan) da taksit oranları alınabilir; conversationId istekte gönderilir, yanıtta aynen döner (iyzico — Refund & Cancel, iyzico — Installment & BIN).

İş kuralı olarak: "aynı gün ise iptal, sonra ise iade" mantığını sisteminize gömün; kullanıcıya kısmi iade yaptığınızda hangi kalem/tutarın iade edildiğini kendi tarafınızda kayıt altına alın ve banka referanslarını saklayın.

Canlıya çıkış öncesi kontrol listesi

• İmza doğrulama: Her callback/webhook için imza doğrulanıyor mu? Doğrulanmayan istek kesin reddediliyor mu? iyzico'da entegrasyon tipinize göre doğru alan sırası mı kullanılıyor?
• Idempotency: Aynı sipariş kimliği (merchant_oid / conversationId) için ikinci kez gelen bildirim tekrar işlenmiyor, yalnızca uygun yanıt dönülüyor mu?
• Hızlı yanıt: Callback beklenen formatta ve hızlı 2xx / OK dönüyor mu? Ağır işler asenkron kuyruğa mı alınıyor?
• Tutar kontrolü: Callback'teki tutar ve para birimi, siparişte beklenen değerle karşılaştırılıyor mu?
• Otorite kaynağı: Sipariş onayı tarayıcı yönlendirmesine değil, sunucu-sunucu bildirimine dayanıyor mu?
• Bekleyen kapama: Callback gelmeyen "başlatılmış ama sonuçlanmamış" ödemeler için arka plan sorgusu var mı?
• İade/iptal: Tam ve kısmi iade, iptal ile taksit senaryoları test edildi mi? Banka referansları saklanıyor mu?
• Sırlar ve HTTPS: secretKey/merchant_key/merchant_salt gibi sırlar sadece sunucuda, ortam değişkenlerinde mi tutuluyor? Callback URL'i HTTPS mi?
• Loglama: Her ödeme olayı (istek, yanıt, callback, imza sonucu) izlenebilir biçimde loglanıyor mu?
• Test ortamı: Sağlayıcının sandbox/test modunda uçtan uca (3DS dâhil) doğrulama yapıldı mı?

Bunu Partnerfy nasıl kurar?

Sakarya merkezli bir B2B / white-label yazılım mühendisliği firması olarak sanal POS entegrasyonunu bir "API çağrısı" değil, bir güvenlik ve mutabakat problemi olarak ele alırız. Bir özel web yazılımı ya da e-ticaret projesinde önce kararı netleştiririz: ödeme kuruluşu mu banka POS'u mu, hosted form mu direkt API mi (PCI-DSS kapsamınıza göre). Ardından 3DS akışını, imza doğrulamalı ve idempotent callback'i, tutar mutabakatını ve iade/taksit senaryolarını uçtan uca kurup test ortamında doğrularız. Bunu genellikle mevcut ERP/muhasebe sistemlerinizle bir API entegrasyonu olarak birbirine bağlarız.

Dürüst bir not: hiçbir entegrasyon "hiç sorun çıkmaz" garantisi veremez — bankalar, sağlayıcılar ve dokümanlar zamanla değişir. Bizim sözümüz garanti değil, disiplin: imzayı doğrulamak, idempotent olmak, otoriteyi callback'e vermek ve her adımı loglayıp mutabık kılmak. Hazır bir eklenti mi yoksa özel bir entegrasyon mu size uygun sorusunu tartışmak isterseniz, özel yazılım mı hazır yazılım mı yazımız da bu kararı çerçevelemenize yardımcı olur.

Sonuç

Üretime hazır bir sanal POS entegrasyonu, API'yi çağırmakla başlar ama orada bitmez. Gerçek iş; doğru kanalı seçmek (ödeme kuruluşu vs banka POS'u), PCI-DSS kapsamını bilinçli daraltmak (hosted vs direkt), 3DS akışını doğru kurmak, callback'i imzayla doğrulamak, idempotent olmak, hızlı 2xx/OK dönmek, tutarı ve siparişi mutabık kılmak ve iade/iptal/taksit senaryolarını eksiksiz yönetmektir. Bu adımların her biri, "çalışıyor gibi görünen" bir entegrasyonu gerçekten güvenli olandan ayırır. Ödeme entegrasyonunuzu tasarlarken ya da mevcut bir kurulumu güvence altına alırken bir yol arkadaşına ihtiyacınız varsa, bizimle iletişime geçin; senaryonuza göre kanal, PCI kapsamı ve mutabakat planını birlikte çıkaralım.

Kaynaklar

• iyzico — Init 3DS (/payment/3dsecure/initialize, threeDSHtmlContent, conversationId)
• iyzico — Auth 3DS (v2 önerilir, paymentId ile tamamlama, mdStatus)
• iyzico — Response Signature Validation (HMAC-SHA256 + HEX)
• iyzico — Webhook (X-IYZ-SIGNATURE-V3, 2xx zorunluluğu, retry)
• iyzico — Installment & BIN Service (/payment/iyzipos/installment)
• iyzico — Refund & Cancel (/payment/refund, /v2/payment/refund, /payment/cancel)
• iyzico — CheckoutForm (hosted ödeme sayfası, PCI kapsamı azalır)
• PayTR — iFrame API 1. adım (paytr_token, hosted iframe, merchant_oid)
• PayTR — iFrame API 2. adım (callback hash, "OK" yanıtı, merchant_oid ile tekilleştirme)
• TCMB — Ödeme Kuruluşları (6493 sayılı Kanun md.12, faaliyet izni)

Sıkça Sorulan Sorular (S.S.S.)