Türk Geliştirici Gözüyle Sanal POS Karşılaştırması: API Kalitesi, SDK ve Sandbox

Önemli Not: Bu yazıdaki teknik bilgiler yazım tarihi itibarıyla geçerlidir. Kullanılan kütüphaneler, API'ler ve servisler zaman içinde değişebilir. Ücretlendirme, yasal düzenleme ve vergi konularında ilgili resmi kaynakları ve uzmanları referans alınız. Bu içerik bilgilendirme amaçlı olup herhangi bir finansal veya hukuki tavsiye niteliği taşımamaktadır.

Google'da "sanal POS karşılaştırma" aratın — onlarca makale çıkar. Hepsi aynı kriterlere bakar: komisyon oranları, anlaşma kolaylığı, müşteri desteği, hangi bankalarla çalışıyor. İş sahibi perspektifinden doğru sorular bunlar.

Ama siz bir geliştiricisiniz. Müşteriniz için e-ticaret entegrasyonu yazıyorsunuz ya da kendi SaaS ürününüzü kuruyorsunuz. Sorularınız farklı:

• npm paketi var mı? Resmi mi, yoksa iki yıldır güncellenmemiş bir community paketi mi?
• TypeScript desteği nasıl? Tip tanımları mevcut mu, yoksa her şeyi any olarak mı kullanacaksınız?
• Sandbox gerçekten çalışıyor mu? Hesap açmadan test edebiliyor musunuz?
• Webhook güvenilir mi? Başarısız delivery durumunda retry var mı?
• Dokümantasyon kalitesi nedir? Kopyalayıp yapıştırabileceğiniz güncel örnekler mevcut mu?
• Geliştirici olarak ne kadar sürede test ortamına erişebiliyorsunuz?

Bu yazı tam o boşluğu dolduruyor. Türkiye'nin önde gelen ödeme sağlayıcılarını — PayTR, İyzico, Craftgate ve Sipay — geliştirici perspektifinden değerlendiriyoruz. Komisyon oranlarına değinmiyoruz (güncel oranlar için her sağlayıcının resmi sitesini ziyaret edin). Burada sadece teknik kriter.

---

İş Sahibi mi, Geliştirici mi? Aynı Soruya Farklı Cevaplar

Bir müşteri gelip "sanal POS kurmanız lazım, hangisini önerirsiniz?" dediğinde, iş sahibi şu soruları sorar:

• Aylık sabit ücret var mı?
• İşlem başı maliyet ne kadar?
• Onay süreci ne kadar sürer?
• Müşteri destek kalitesi nasıl?
• TCMB lisansı var mı?

Geliştirici ise şunları düşünür:

• Bu entegrasyonu yazmak kaç gün sürer?
• Hata ayıklamak için iyi bir sandbox var mı?
• Webhook endpoint'im için güvenilir bir mekanizma var mı?
• Bir yıl sonra kütüphane güncel mi olacak?
• TypeScript projeme uyum sağlıyor mu?

Bu iki perspektif çoğu zaman örtüşmez. İş sahibi için en ucuz olan sağlayıcı, geliştirici için en pahalı (zamanı açısından) olabilir. Tersine, geliştirici dostu bir sağlayıcının ticari koşulları her müşteriye uygun olmayabilir.

---

Regülasyon Notu: TCMB, BDDK Değil

Türkiye'de ödeme kuruluşları sıkça "BDDK lisanslı" olarak anılır — bu teknik olarak yanlış. 2019'dan itibaren ödeme kuruluşlarının denetimi BDDK'dan TCMB'ye (Türkiye Cumhuriyet Merkez Bankası) geçti. 6493 sayılı Ödeme ve Menkul Kıymet Mutabakat Sistemleri Kanunu kapsamında tüm ödeme kuruluşları TCMB tarafından lisanslandırılır ve denetlenir.

Bu bilgi, müşterilerinize veya teknik dokümanlara sağlayıcıyı tanıtırken doğru ifadeyi kullanmanız açısından önemli.

---

Geliştirici Değerlendirme Kriterleri

Karşılaştırmaya geçmeden önce her kriterin ne anlama geldiğini tanımlayalım.

1. npm Paketi ve Bakım Durumu

Sağlayıcının resmi bir npm paketi var mı? Resmi paket yoksa topluluk alternatifleri ne durumda? Son commit tarihi ne zaman? Bu sorular önemli çünkü bakımsız bir kütüphane, API değiştiğinde sizi mahvedebilir.

2. TypeScript Desteği

Paket TypeScript ile mi yazılmış? Tip tanımları (d.ts) tam mı? TypeScript desteği olmayan bir paketi modern Next.js projesinde kullanmak, ya her şeyi any ile geçiştirmek ya da kendi tip tanımlarını yazmak demek — ikisi de istenmeyen durumlar.

3. Sandbox Ortamı Kalitesi

Sandbox'a erişim için tam başvuru süreci mi gerekiyor, yoksa anında kullanabilir misiniz? Test kartları var mı? Başarılı ödeme, başarısız ödeme, 3DS senaryolarını simüle edebiliyor musunuz?

4. Webhook Güvenilirliği

Ödeme tamamlandığında sağlayıcı sitenize bir POST isteği atar (webhook/postback). Bu mekanizma ne kadar güvenilir? Başarısız delivery durumunda otomatik yeniden deneme (retry) var mı? Kaç kez deniyor? Hash doğrulama standartları nedir?

5. Dokümantasyon Kalitesi

Dokümantasyon güncel mi? Kopyalayıp yapıştırılabilir kod örnekleri var mı? Türkçe mi, İngilizce mi? Sık sorulan hataları kapsıyor mu?

6. Geliştirici Onboarding Süresi

Sandbox'a "ilk API isteğini atmak" için ne kadar bekliyorsunuz? Bazı sağlayıcılarda anında test başlayabilirsiniz; bazılarında iş birimi onayı beklemeniz gerekir.

---

SDK Kalite Karşılaştırması

Aşağıdaki tablo, Mart 2026 itibarıyla doğrulanmış teknik verilere dayanmaktadır.

*Stripe Türkiye durumu için aşağıdaki bölüme bakın.

İyzico — En Büyük Hacim, TypeScript Eksikliği

İyzico, Türkiye'nin işlem hacmi bakımından en büyük ödeme sağlayıcısıdır. Sahibinden.com, Decathlon, LetGo gibi büyük platformlar tarafından kullanılmaktadır. Mart 2026'da yapılan önemli bir değişiklik: İyzico, Moka değil PayU tarafından satın alındı (1 Nisan 2025, $165M). Marka adı "iyzico" olarak devam etmektedir.

Geliştirici perspektifinden:

• Resmi npm paketi iyzipay mevcut ve aktif olarak güncelleniyor (son sürüm: v2.0.65)
• TypeScript desteği yok — paket %100 JavaScript ile yazılmış
• TypeScript projelerinde kendi tip tanımlarınızı yazmanız ya da @types/iyzipay gibi topluluk tiplerini kullanmanız gerekiyor
• Checkout Form (iframe) ve Direct API olmak üzere iki entegrasyon yöntemi mevcut
• Sandbox ortamı erişilebilir; test kartları kapsamlı
• Webhook (IPN) sistemi var, 10 dakikada bir maksimum 3 yeniden deneme yapıyor
• Sub-merchant (marketplace) desteği mevcut

Craftgate — En İyi Geliştirici Deneyimi

Craftgate, tek bir API üzerinden tüm Türk bankalarına erişim sağlayan ödeme orkestrasyonu platformudur. Ocak-Mayıs 2025'te 76,86 milyar TL işlem hacmi ile %140 büyüme kaydetti. Geliştirici ekosisteminde hızla büyüyen bu platform, teknik açıdan en olgun ödeme çözümü olarak öne çıkıyor.

Geliştirici perspektifinden:

• Resmi npm paketi @craftgate/craftgate mevcut ve aktif (v1.0.65, 320+ commit, 66 sürüm)
• TypeScript desteği tam — %65 TypeScript ile yazılmış, tip tanımları eksiksiz
• Sandbox ortamı https://sandbox-api.craftgate.io adresiyle ayrı bir domain olarak mevcut
• Akıllı yönlendirme (Smart Routing): Yapılandırılmış banka POS'ları arasından otomatik en uygun yönlendirme
• Failover routing: Ödeme başarısız olduğunda otomatik banka değişimi
• Taksit sorgulama API'si dinamik ve BIN bazlı çalışıyor
• Sub-merchant (marketplace) desteği tam — escrow ve anlık settlement destekli
• Komisyon yapısı benzersiz: Craftgate sabit oran uygulamaz, merchant kendi banka anlaşmalarıyla çalışır; Craftgate aralarında yönlendirme yapar

Ajans veya freelancer olarak birden fazla müşteri için entegrasyon yazıyorsanız, Craftgate'in tek SDK'sı üzerinden tüm bankalar ve POS'lara erişme konsepti ciddi geliştirici avantajı sağlıyor.

PayTR — En Popüler KOBİ Seçimi, Resmi SDK Yok

PayTR, KOBİ segmentinde en yaygın kullanılan ödeme çözümüdür. Hızlı onboarding ve geniş kullanıcı tabanı nedeniyle tercih edilmektedir.

Geliştirici perspektifinden:

• Resmi npm paketi yok — Bu en büyük dezavantaj
• Topluluk alternatifi paytr-js (GitHub: themisir/paytr-js): ~%99 TypeScript, iframe token ve basket yönetimi kapsıyor, ancak İade API dahil değil
• node-paytr: JavaScript, 12+ aydır güncelleme yok — production için önerilmez
• Sandbox ayrı bir ortam değil: test_mode=1 parametresiyle production API'si üzerinde test yapılır
• Test kartları mevcut ve kapsamlı (3 farklı kart numarası)
• Postback (webhook) sistemi var; ancak retry mekanizması daha sınırlı
• HMAC-SHA256 token oluşturma mantığı manuel olarak implement edilmesi gereken kritik bir adım — alan sırası hatası yaygın bir sorun
• Tekrarlayan ödeme (abonelik) için ayrı banka yetkisi gerekiyor

Resmi SDK eksikliği, özellikle TypeScript projelerinde geliştirme süresini uzatabiliyor. Öte yandan HMAC mantığı iyi belgelenmiş ve topluluk kaynakları yeterli.

Sipay — Büyüyen Alternatif, Topluluk SDK

Sipay, 2025 yılında $78 milyon yatırım alan ve hızla büyüyen bir alternatif. Çoklu para birimi desteği ve aylık sabit ücret olmaması gibi ticari avantajları var.

Geliştirici perspektifinden:

• npm paketi mevcut (@muhammedaksam/sipay-node) ancak topluluk paketi — resmi değil
• TypeScript desteği var
• Sandbox apidocs.sipay.com.tr üzerinden erişilebilir
• Ekosistem henüz PayTR veya Craftgate kadar olgun değil; topluluk kaynakları sınırlı

---

3DS Durumu: Türkiye'de Zorunlu

Karşılaştırma tablosuna bakarken göz önünde bulundurmanız gereken önemli bir Türkiye özelliği var: 3D Secure Türkiye'de pratik olarak zorunlu.

Tüm Türk bankaları SMS OTP tabanlı 3DS v1 uygular. non_3d modu yalnızca kayıtlı kart veya tekrarlayan ödemeler için kullanılabilir ve bunun için ayrı banka yetkisi gerekir. Yani entegrasyon geliştirirken 3DS akışını (yönlendirme, callback, doğrulama) baştan planlamanız gerekiyor — tüm sağlayıcılar için bu geçerli.

---

Detaylı Kriter Karşılaştırması

Güncel komisyon oranları için her sağlayıcının resmi sitesini ziyaret edin.

---

Senaryo Bazlı Öneri

Her proje farklı gereksinimler taşır. İşte en yaygın senaryolar için rehberimiz:

KOBİ için ilk e-ticaret sitesi kuruyorsunuz

PayTR önerilir. Hızlı onboarding, geniş topluluk ve bol Türkçe kaynak avantajı sağlıyor. TypeScript eksibi olmayan veya hızlı sonuç gereken projelerde tercih edilebilir. İlk entegrasyonu yazmak için paytr-js topluluk paketi yeterli.

Büyük hacimli pazar yeri veya multi-vendor platform

İyzico veya Craftgate önerilir. İkisi de sub-merchant desteği sunuyor. İyzico Türkiye'de en geniş banka bağlantısı ve kabul oranlarına sahip. Craftgate, akıllı yönlendirme sayesinde tek banka üzerindeki başarısızlıklara karşı otomatik failover sağlıyor.

Ajans veya freelancer — birden fazla müşteri entegrasyonu

Craftgate önerilir. Tek API üzerinden tüm bankalara erişim, her müşteri için ayrı banka anlaşması yapmak yerine Craftgate üzerinden yönlendirme yapma imkânı ciddi zaman tasarrufu sağlıyor. Üstelik TypeScript desteği tam — tip güvenli kod yazabiliyorsunuz.

Abonelik / tekrarlayan ödeme sistemi

PayTR veya İyzico değerlendirilebilir. PayTR'de recurring için ayrı banka yetkisi gerekiyor ve zamanlamayı siz yönetiyorsunuz. İyzico'da da benzer koşullar var. Her iki sağlayıcı için de banka ile görüşme süreci planlamanız gerekiyor.

Uluslararası müşterilerden ödeme almak istiyorsunuz

Stripe (yabancı şirket üzerinden) veya çoklu gateway mimarisi. Türk kullanıcılar → yerli sağlayıcı (PayTR/İyzico/Craftgate), yabancı kullanıcılar → Stripe kombinasyonu ideal. Detaylar için Stripe Türkiye bölümüne bakın.

---

Stripe ve Türkiye: Gerçek Durum

Stripe, özellikle uluslararası referanslarda sıkça geçiyor. Türk geliştirici olarak bilmeniz gereken kritik bilgi:

Türkiye'ye kayıtlı şirketler ve bireyler Stripe hesabı açamaz, Türk IBAN bağlayamaz.

Bu bir kural değil, Stripe'ın desteklenen ülkeler listesinden kaynaklanıyor. Türkiye bu listede yer almıyor.

Stripe kullanmak için iki yol var:

1. Stripe Atlas ile ABD LLC kurmak: Stripe'ın kendi şirket kurma hizmeti. Bir ABD LLC oluşturarak Stripe hesabı açabilirsiniz. Yasal ve muhasebe gereksinimleri doğuruyor.
2. AB şirketi: İngiltere veya AB ülkesinde şirket kurarak Stripe kullanımı.

Her iki seçenek de ek maliyet ve yasal karmaşıklık içeriyor. Bu konuyu değerlendiriyorsanız mutlaka bir mali müşavir veya avukattan destek alın.

Türkiye'deki kullanıcılara ödeme aldıktan sonra uluslararası faturalama da yapmak istiyorsanız, çoklu gateway mimarisi (Türk kullanıcı → yerli sağlayıcı, yabancı kullanıcı → Stripe) kurgulamak en temiz çözüm.

---

2026 Trendleri: Geliştirici Perspektifinden

Craftgate'in Büyümesi Ekosistemi Güçlendiriyor

76 milyar TL işlem hacmi ve %140 büyümeyle Craftgate, 2026'da geliştirici ekosistemi için en aktif yatırım yapan platform konumuna geliyor. SDK'nın aktif geliştirilmesi, yeni API özelliklerinin hızlı eklenmesi ve artan Türk geliştirici topluluğu katkısı bekleniyor.

Open Banking Dalgası Yaklaşıyor

TCMB'nin Open Banking düzenlemeleri çerçevesinde Türkiye'de hesap-to-hesap ödeme altyapısı olgunlaşıyor. 2026-2027 döneminde ödeme sağlayıcılarının API'lerine açık bankacılık endpoint'leri eklemesi bekleniyor. Craftgate bu alanda da aktif.

TypeScript Zorunluluk Oluyor

Next.js 16, Bun ve modern TypeScript ekosistemi baskısıyla sağlayıcıların TypeScript desteğini bir tercih değil, zorunluluk olarak görmesi gerekiyor. İyzico'nun JavaScript tabanlı SDK'sı bu baskı altında önümüzdeki dönemde tip desteği eklemek zorunda kalabilir.

Webhook Standartları Yükseliyor

Stripe'ın Stripe-Signature header standardı, Türk sağlayıcıların webhook güvenlik mekanizmalarına da baskı yapıyor. HMAC tabanlı doğrulama artık standart; imzalı payload ve idempotency key desteği beklenen bir özellik haline geliyor.

---

Hangisini Seçmeli? Karar Rehberi

Hedefim nedir?
│
├─ Hızlı KOBİ e-ticaret → PayTR
│    (onboarding hızı + büyük topluluk + Türkçe kaynak)
│
├─ Yüksek hacim / pazar yeri → İyzico
│    (sub-merchant + geniş banka kabul oranı)
│
├─ Ajans / çok müşterili → Craftgate
│    (tek SDK + akıllı yönlendirme + TypeScript)
│
├─ Abonelik sistemi → PayTR veya İyzico
│    (banka yetkilendirmesi şart, önceden planlayın)
│
└─ Uluslararası gelir → Craftgate (TR) + Stripe (yabancı)
     (yabancı şirket kurmanız gerekiyor, danışmanınıza sorun)

---

Sıkça Sorulan Sorular

Hangi sağlayıcıda TypeScript desteği en iyi?

Craftgate açık ara öne çıkıyor. Resmi @craftgate/craftgate paketi %65 TypeScript ile yazılmış ve tam tip desteği sunuyor. Sipay'ın topluluk paketi de TypeScript içeriyor. PayTR için topluluk paketi paytr-js yaklaşık %99 TypeScript, ancak resmi değil. İyzico'nun iyzipay paketi %100 JavaScript — TypeScript projelerinde ek iş gerektiriyor.

Sandbox'a erişim için ne kadar beklemem gerekiyor?

Craftgate'de ayrı bir sandbox domain (sandbox-api.craftgate.io) mevcut ve genellikle hızlı erişim sağlanıyor. İyzico sandbox'ına da görece hızlı erişilebiliyor. PayTR'de sandbox ayrı bir ortam değil; production API'si üzerinde test_mode=1 parametresiyle çalışıyorsunuz, bu da hesap onay sürecine bağlı.

Webhook başarısız olursa ne olur?

İyzico, başarısız webhook delivery durumunda 10 dakikada bir maksimum 3 yeniden deneme yapıyor. Bu süre zarfında endpoint'iniz 200 dönmezse bildirimi kaçırabilirsiniz. Bu nedenle idempotency (aynı webhook'u iki kez işlememe) ve retry toleransı için veritabanı seviyesinde bir mekanizma kurmanız önerilir. Diğer sağlayıcıların retry politikaları için güncel dokümantasyonlarını inceleyin.

Marketplace kuruyorsam hangi sağlayıcıyı tercih etmeliyim?

Sub-merchant (pazar yeri) desteği için hem İyzico hem Craftgate güçlü seçenekler sunuyor. Craftgate'in escrow ve anlık settlement desteği özellikle para akışı karmaşık olan platformlar için avantajlı. İyzico'nun büyük platform referansları (Sahibinden, LetGo gibi) güven verici. Her iki sağlayıcıyla da ticari koşullar için doğrudan görüşmeniz gerekiyor.

Stripe olmadan yabancı kullanıcıdan ödeme alabilir miyim?

Evet. Wise Business ve Payoneer gibi platformlar üzerinden yabancı para biriminde ödeme alabilirsiniz. Craftgate'in çoklu para birimi desteği (USD, EUR, GBP ve daha fazlası) de değerlendirilebilir. Yasal durum, vergi yükümlülükleri ve en uygun çözüm için mutlaka bir mali müşavire danışın.

PayTR için resmi npm paketi neden yok?

PayTR, resmi bir npm paketi yayınlamıyor. Şirketin odağı daha çok merchant panel ve direkt API dokümantasyonu üzerine. Topluluk tarafından geliştirilen paytr-js paketi temel kullanım için yeterli olsa da kritik production senaryoları için doğrudan REST API üzerinde kendi implementasyonunuzu yazmanız daha güvenli bir yaklaşım olabilir.

---

Sonuç

Sanal POS seçimi, iş sahibi için ticari bir karar; geliştirici için teknik bir karar. İkisini aynı anda doğru yapmak, proje başında net değerlendirme yapmanızı gerektiriyor.

Özet olarak:

• TypeScript projesi + ajans iş modeli → Craftgate
• Hızlı başlangıç + KOBİ → PayTR
• Büyük hacim + marketplace → İyzico
• Uluslararası gelir → Craftgate (TR) + Stripe (yabancı, yabancı şirket üzerinden)

Bu sitedeki e-ticaret projelerinde PayTR ile aktif çalışıyoruz. Entegrasyon detayları için Next.js + PayTR rehberine göz atabilirsiniz.

Hangi sağlayıcıyı seçerseniz seçin: ticari koşullar için her sağlayıcının güncel tarifesini doğrudan resmi sitesinden kontrol edin, yasal ve vergisel yükümlülükler için mali müşavirinize danışın.

---

Bu yazı Mart 2026 itibarıyla doğrulanmış teknik verilere dayanmaktadır. npm paket sürümleri, API endpoint'leri ve sandbox adresleri değişebilir — entegrasyon öncesinde resmi dokümantasyonu kontrol edin.