Sanal POS kararında atlanan üç teknik soru: API, webhook ve sandbox

Ödeme işlemini hangi API üzerinden başlatacağını, işlem sonucunun sunucusuna nasıl ulaşacağını ve canlıya çıkmadan önce hata senaryolarını nerede deneyeceğini sorar.

Bu üç sorunun cevabı sözleşmeden sonra öğrenildiğinde karar geri alınamaz ama bedeli görünür hale gelir: entegrasyon planlanandan uzun sürer, ödemesi tamamlandığı halde siparişi açık kalan müşteriler destek hattına düşer, ilk iade talebinde ekip veritabanını elle düzeltir. Soruların üçü de değerlendirme aşamasında sorulduğunda kimseye bir maliyet çıkarmaz.

Ticari masa ile teknik masa neden farklı şeylere bakıyor

Karar vericinin baktığı kalemler işlem başına tekrarlayan ve muhasebede doğrudan karşılığı olan maliyetlerdir. Kurulum ücretinin ₺0 olması, aylık sabit ücret alınmaması ya da tahsilatın T+1 ile hesaba geçmesi bu türden bilgilerdir. Komisyon oranı da aynı masada konuşulur; SanalPos.com bu oranı işletmeye özel belirliyor ve kart ailesi, taksit sayısı, aylık işlem hacmi ile sektörü hesaba katıyor.

Yazılımcının baktığı kalem ise tek seferlik görünür fakat tekrarlayan bir yük üretir: entegrasyonun kendisi. Bir ödeme akışı yazıldıktan sonra ürünün her yeni özelliğiyle birlikte bakım ister. Abonelik başlatmak, kart saklamak, kısmi iade yapmak, taksitli ve tek çekim işlemleri ayrı raporlamak, bunların hepsi aynı entegrasyonun üzerine biner.

Bazı kalemler iki listede birden yer alır. Altyapının %99.9 uptime ile çalışması hem geliştiricinin hem karar vericinin ilgi alanındadır, çünkü kesinti aynı anda hem koda hem ciroya yansır. İki masanın ortak dili genellikle burada kurulur.

Teknik ekibin erken netleştirdiği bir başka nokta modelin kendisidir. SanalPos.com, Lirbon Teknoloji ve Elektronik Ticaret A.Ş. çatısı altında yürüyen bir yazılım hizmetidir; ödeme kuruluşu ya da elektronik para kuruluşu statüsünde değildir. Sunduğu şey teknik ödeme altyapısıdır ve başarılı işlemin bedeli, üye işyeri adına tanımlı sanal POS üzerinden işletmenin kendi banka hesabına aktarılır. Bu ayrım mutabakat ve raporlama tarafındaki kodun neye göre yazılacağını belirlediği için aynı zamanda teknik bir sorudur.

Birinci soru: API entegrasyon yüzeyinin ne kadarını kapsıyor

Ödeme entegrasyonunun ilk sorusu, dilin hangi seviyede konuşulacağıdır. Hazır eklenti kuran bir ekip sağlayıcının hazırladığı akışı olduğu gibi devralır. Ödeme linki kullanan bir işletme kod yazmadan tahsilat yapar. REST API üzerinden entegre olan bir ekip ise ödeme akışının her adımını kendi ürününün içine yerleştirir. Üçü de ödeme almayı sağlar, üçü aynı işi yapmaz.

Bu soruyu somutlaştırmanın yolu sağlayıcının geliştirici dokümantasyonunu açmaktır. SanalPos.com tarafında yayında olansanal POS altyapısı REST API ve webhook desteğinin yanında PHP, Node.js ve Python için SDK sunuyor; hazır eklentiler, ödeme linki ve kodsuz POS ise kod yazmadan başlamak isteyen işletmeler için ayrı seçenekler olarak duruyor.

Doğru seviye ürünün ihtiyacına göre değişir. Tek seferlik satış yapan bir siteye eklenti çoğu zaman yeter. Abonelik yenileyen, kart saklayıp tek tıkla ödeme alan, birden çok para biriminde fiyatlayan, bayi tahsilatını kendi paneline gömen ya da satış kayıtlarını Logo, Luca veya Paraşüt tarafına akıtan bir ürün API seviyesine iner. Tokenization, otomatik abonelik yönetimi ve 10'dan fazla para biriminde ödeme SanalPos.com tarafında ayrı başlıklar olarak yayında; teknik ekibin bakması gereken şey, bu başlıkların dokümantasyonda hangi uçlarla karşılandığıdır.

Taksit de aynı yüzeyin parçasıdır. Visa, Mastercard, Troy ve American Express olmak üzere 4 kart ağı ile 9'dan fazla taksit programı söz konusu olduğunda yazılımcının sorusu şudur: taksit seçeneği istekte nasıl belirtiliyor ve müşteriye gösterilecek liste hangi kaynaktan çekiliyor. Bu iki cevap bilinmeden ödeme ekranının nasıl görüneceği de tasarlanamaz.

Yazılımcının dokümantasyonda aradığı şey özellik adı değil, uçların davranışıdır.

• Ödeme başlatma, iptal, tam iade ve kısmi iade işlemlerinin ayrı ayrı tanımlanmış olması
• Taksitli işlem ile tek çekim arasındaki farkın istek gövdesinde nasıl kurulduğu
• Kart saklama ve saklanan kartla tekrar tahsilat akışının hangi adımlardan geçtiği
• Hata kodlarının tam listesi ve her kodun kullanıcıya hangi mesajla karşılık geldiği
• Test ortamı ile canlı ortam arasındaki adres ve anahtar farkının nasıl yönetildiği

Sitede geçen "15 dakikada entegrasyon" ifadesinin hangi yola karşılık geldiğini sormak da bu başlığa girer. Onay sonrası API, hazır eklenti veya ödeme linkiyle ödeme almaya başlanabildiği yazılıdır; ancak bir eklentiyi kurmakla özel bir sepet akışını kodlamak aynı iş değildir. Teknik ekip bu cümleyi kendi seçtiği yola göre okur.

İkinci soru: işlem sonucu sunucunuza nasıl ulaşıyor

Ödeme akışının en kırılgan yeri müşterinin tarayıcısıdır. Kart doğrulaması 3D Secure ekranında tamamlandıktan sonra kullanıcı sitenize geri döner ve sipariş çoğu kurulumda o dönüşte kapatılır. Kullanıcı dönüş tamamlanmadan sekmeyi kapatırsa, mobil verisi kesilirse ya da geri tuşuna basarsa banka tarafında başarılı olan işlem sizin tarafınızda hiç olmamış gibi durur.

Webhook tam olarak bu boşluğu kapatır. Sağlayıcının sunucusu, tarayıcıdan bağımsız biçimde sizin belirlediğiniz adrese işlem sonucunu bildirir. SanalPos.com tarafında webhook desteği yayında olduğu için sipariş durumunu kullanıcının geri dönüşüne bağlamak zorunda kalmazsınız.

Bildirimin ilgilendirdiği tek senaryo başarılı ödeme değildir. İade, kısmi iade, chargeback ve abonelik yenilemesi gibi olaylar müşteri sitede değilken gerçekleşir. Bunların sipariş kaydına, stok hareketine ve dijital ürün teslimine yansıması için sonucun bir yere düşmesi gerekir.

Bildirimi almak yeterli değil, doğru işlemek de gerekir. Aynı bildirimin ağ hatası nedeniyle iki kez ulaşması olağandır; ödeme kaydı ikinci kez işlenmemeli, sipariş iki defa hazırlanmamalıdır. Bildirimin gerçekten sağlayıcıdan geldiğinin doğrulanması da aynı kapsamdadır. Bu iş yazılım ekibine düşer, ama sorunun sözleşme öncesinde sorulmuş olması gerekir.

Burada bir ayrım da kayda geçmelidir: bildirim akışı ile para akışı aynı şey değildir. Webhook işlemin başarılı olduğunu saniyeler içinde söyler; tahsilatın işletmenin banka hesabına geçmesi ise T+1 ile yürür. Bu iki zamanı aynı sanan bir muhasebe kurgusu ilk ay içinde tutmaz.

Üçüncü soru: sandbox neyi denemenize izin veriyor

Ödeme kodunu ilk kez canlıda sınamak pahalı bir alışkanlıktır. Sandbox, gerçek para hareketi olmadan aynı akışı çalıştırabildiğiniz test ortamıdır; test kartları da bu ortamda belirli sonuçları kasten üretmek için kullanılır. SanalPos.com geliştirici sandbox ortamı ve test kartları sunuyor.

Sandbox'ın asıl değeri başarılı işlemi denemekte değil, başarısız işlemi denemektedir. Canlıda karşınıza çıkacak durumların çoğu, her şeyin yolunda gittiği akışın dışında kalır.

• Yetersiz bakiye veya limit aşımı nedeniyle reddedilen kart
• 3D Secure doğrulamasının tamamlanmaması ya da yanlış kod girilmesi
• Ödeme sırasında zaman aşımı ve kullanıcının işlemi yarıda bırakması
• Tam iade ile kısmi iadenin sipariş kaydında ayrı yürümesi
• Taksitli işlemin tek çekimden farklı raporlanması
• Aynı bildirimin ikinci kez gönderilmesi

Sandbox aynı zamanda kart verisinin sizin sistemlerinize hiç uğramadığını doğrulamanın yeridir. SanalPos.com altyapısı PCI-DSS uyumlu, 3D Secure tüm hesaplarda varsayılan olarak açık ve trafik 256-bit SSL ile şifreleniyor. Ekibin test sırasında kontrol etmesi gereken şey somuttur: kendi loglarına, hata kayıtlarına ve veritabanına kart numarası düşüyor mu.

SmartCheck gibi sahtecilik önleme ve risk skorlama katmanı da bu aşamada gündeme gelir. Bir işlemin risk nedeniyle durdurulması, ürün tarafında başarılı ve başarısızdan ayrı üçüncü bir durum üretir. Kullanıcıya ne gösterileceği ve siparişin hangi durumda bekletileceği canlıda değil test ortamında kararlaştırılmalıdır.

Üç sorunun satın alma kararındaki karşılığı

Bu sorular teknik merak değildir; her biri ticari bir sonucu belirler.

Tablonun sağ sütunu komisyonla aynı türden bir maliyet değildir. Komisyon işlem başına ölçülür ve tahmin edilebilir; sağ sütundaki kalemler geliştirici saatine, destek hattına ve gecikmiş lansmana yayılır. İkisi aynı karşılaştırma tablosunda yan yana durmadığı için de karar masasında kolayca gözden kaçar.

Teknik değerlendirmeyi takvimin neresine koymalı

Bu üç sorunun sorulma zamanı, cevabından daha belirleyicidir. Değerlendirme aşamasında sorulduklarında yanıtları dokümantasyondan okunur ve karar buna göre şekillenir. Entegrasyon aşamasında sorulduklarında ise yanıt artık bir tercih değil, kısıttır.

İşleyen sıra şudur: teknik ekip dokümantasyonu ticari görüşmeyle aynı hafta içinde okur, sandbox erişiminin hangi aşamada verildiğini sorar ve webhook adresini kendi test sunucusuna bağlayıp bağlayamayacağını netleştirir. Dokümantasyon okumak sözleşme gerektirmez; sandbox erişiminin koşulu ise doğrudan sağlayıcıya sorulacak bir sorudur.

Başvuru tarafının nasıl işlediğini bilmek de bu planlamayı kolaylaştırır. SanalPos.com'da form 30 saniye sürüyor, hesap e-posta doğrulamasıyla açılıyor, belgeler panelden yükleniyor ve belgeler eksiksizse başvuru 24 saat içinde sonuçlanıyor. Ticari onayı beklerken teknik hazırlığın tamamen durmasını gerektiren uzun bir boşluk oluşmuyor.

Karar vericinin yapması gereken tek şey, sağlayıcı listesini daraltmadan önce kendi ekibine üç soruyu sormaktır: API neyi kapsıyor, ödeme sonucu bize nasıl ulaşıyor, hataları nerede deneyebiliriz. Bu üç cevap elde olduğunda imzadan sonra çıkan sürprizlerin çoğu, düzeltilmesi çok daha ucuz bir aşamaya taşınmış olur.

Sık sorulan sorular

Hazır eklenti kullanan bir işletmeyi webhook yine de ilgilendirir mi

Evet. Eklenti sipariş durumunu kendi mantığıyla günceller, ancak iade, chargeback ve abonelik yenilemesi gibi olaylar eklentinin başlattığı akışın dışında da gerçekleşir. Eklentinin bu bildirimleri karşılayıp karşılamadığı, canlıya çıkmadan önce netleşmesi gereken bir konudur.

SDK varsa API dokümantasyonunu okumak gerekmez mi

SDK isteklerin hazırlanmasını kolaylaştırır, uçların davranışını değiştirmez. Hata kodlarının anlamı, iade kurallarının sınırı ve bildirim akışı yine API tarafında tanımlıdır. PHP, Node.js veya Python SDK'sı kullanan bir ekip de bu tanımlara bakmak zorundadır.

Test kartlarıyla yapılan işlemler gerçek bir para hareketi yaratır mı

Hayır. Sandbox ortamı canlı ortamdan ayrıdır ve test kartları gerçek kart bilgisi değildir; amaçları belirli sonuçları kasten üretmektir. Canlıya geçerken yapılması gereken kontrol, ortam adreslerinin ve anahtarların gerçekten değiştirilmiş olduğunu doğrulamaktır.