Webhook ile Callback Arasındaki Fark
Callback, ödeme sayfasında işlemi bitiren kullanıcının tarayıcısıyla sitenize geri dönmesidir. Kullanıcı sayfayı kapatırsa, bağlantısı koparsa ya da yönlendirme tamamlanmazsa bu dönüş hiç gerçekleşmeyebilir. Bu yüzden callback, kullanıcıya sonuç ekranı göstermek için uygundur; siparişin gerçekten ödendiğine karar vermek için tek başına yeterli değildir.
Webhook ise ödeme tarafındaki sunucunun, kullanıcıdan bağımsız olarak sizin sunucunuza gönderdiği bir HTTP isteğidir. Genellikle POST yöntemiyle, gövdesinde JSON taşıyan bir istek gelir; içinde işlem kimliği, sipariş numarası, tutar ve sonuç durumu gibi alanlar bulunur. Alan adları ve olay tipleri, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Pratikte iki mekanizma birlikte kullanılır: kullanıcı callback ile karşılanır, kayıt webhook ile kesinleştirilir.
Bildirim Almak ve İmzayı Doğrulamak
Bildirimi karşılayacak adres herkese açık bir HTTPS adresi olmalı ve oturum çerezi ya da kullanıcı girişi beklememelidir; isteği gönderen taraf sizin oturumunuza sahip değildir. Adresin kendisi de bir sır değildir; bu nedenle güvenlik adresin gizliliğine değil, imza doğrulamasına dayanır.
Doğrulamanın genel mantığı şudur: gelen isteğin gövdesi ham haliyle, ayrıştırılmadan ve yeniden serileştirilmeden alınır; paylaşılan gizli anahtarla bu gövdeden bir imza üretilir ve istek başlığında gelen imzayla karşılaştırılır. İki değer eşleşmiyorsa istek işlenmeden reddedilir. Karşılaştırmayı sabit süreli bir fonksiyonla yapmak iyi bir alışkanlıktır. Kullanılan imza yöntemi, başlık adı ve gizli anahtarın nasıl iletildiği seçilen ödeme kuruluşunun çözümüne göre değişir; ayrıntısı hesabınıza verilen API dokümantasyonu içinde belirtilir.
İmza geçerliyse bildirimi hemen baştan sona işlemek yerine kaydedip 2xx yanıtı döndürmek genellikle daha sağlıklıdır. Fatura kesme, e-posta gönderme, stok düşme gibi işleri kuyruğa alın; yanıtı geciktiren uzun işlemler, karşı tarafın teslimatı başarısız sayıp yeniden denemesine yol açabilir.
Yeniden Gönderim ve Idempotency
Sunucunuz yanıt veremezse veya hata döndürürse aynı olay bir süre sonra tekrar gönderilir. Deneme sayısı ve bekleme aralıkları seçilen çözüme göre değişir; tasarım açısından önemli olan nokta, aynı bildirimin birden fazla kez ulaşabileceğini varsaymanızdır.
Bunun çözümü idempotency'dir: aynı olay kaç kez işlenirse işlensin sonuç değişmemelidir. Uygulamada bildirimdeki olay ya da işlem kimliği benzersiz bir sütunda saklanır; her gelen bildirimde önce bu kayıt aranır. Kayıt varsa iş tekrarlanmadan 2xx dönülür, yoksa sipariş güncellenir ve kimlik yazılır. Sipariş durumunu güncellerken geriye dönüşü de engelleyin: başarıyla kapanmış bir sipariş, sonradan ulaşan eski bir bildirimle geri açılmamalıdır.
Bildirimleri ham gövde, başlıklar ve alınma zamanıyla birlikte günlüğe yazmak sorun çözmeyi kolaylaştırır. Dönen sonuç kodlarının karşılığı için POS hata kodları sayfasına bakabilirsiniz. Günlüklerde kart numarası, CVV ve benzeri veriler tutulmamalıdır.
Test Ortamında Deneme ve Canlıya Geçiş
Bildirim akışını canlıya almadan önce test ortamında uçtan uca çalıştırın. Ödeme senaryolarını test ortamı (sandbox) ve test kartları ile deneyip başarılı, başarısız ve doğrulama adımında kalan işlemlerde sunucunuza hangi bildirimlerin ulaştığını izleyebilirsiniz. Geliştirme sırasında yerel makineniz dışarıdan erişilebilir olmadığı için, isteği dışarıya açan bir tünel aracıyla ya da sunucuya konulan basit bir alıcı uçla çalışmak pratiktir.
Denemeye değer senaryolar: imzayı bilerek bozup isteğin reddedildiğini görmek, aynı bildirimi iki kez işleyip siparişin tek kez kapandığını doğrulamak ve yanıt vermeyen bir uç bırakıp yeniden gönderimin geldiğini gözlemlemek.
Canlıya geçerken test anahtarları yerine canlı anahtarlar ve canlı callback adresi kullanılır. Entegrasyonun tamamı için entegrasyon kılavuzu, hazır örnekler için örnek kodlar ve PHP, Node.js, Python SDK sayfalarına bakabilirsiniz. API tarafının genel görünümü için API ve SDK entegrasyonu sayfası da yardımcı olur.
