python-est

python-est, Türkiye'de EST altyapısını kullanan bankaların sanal POS hizmetini Python ile yazılmış web projelerine eklemek için hazırladığım örnek kodlar. Ödeme formunun hazırlanmasını, işlemin güvenlik özetinin (hash) üretilmesini ve 3D Secure doğrulamasından dönen sonucun yorumlanmasını adım adım gösteriyor. Kodları Django çatısıyla, 2014 yılının Ocak ayında yazdım ve depoyu sonraki yıllarda güncelledim.

Amaç

Sanal POS, bir web sitesinin kredi kartıyla ödeme alabilmesi için bankanın sağladığı hizmet. EST, o dönemde Türkiye'de birçok bankanın kullandığı ortak bir sanal POS altyapısıydı. Bu altyapıyla entegrasyon yapmak isteyen bir geliştiricinin karşısına çok sayıda parametre ve uzun teknik belgeler çıkıyordu. Ben de kendi projemde entegrasyonu tamamladıktan sonra, kafa karıştıracak ayrıntılara girmeden doğrudan projeye eklenip test edilebilecek kodları paylaşmak istedim. Amacım, aynı işi yapacak başka geliştiricilerin ilk çalışan ödemeye daha kısa sürede ulaşmasıydı.

Nasıl çalışır

Akış iki Django görünümünden (view) oluşuyor. Birinci görünüm, satın alınacak ürünün fiyatını veritabanından alıyor. Ardından her işlem için rastgele bir sipariş numarası ve rastgele bir değer üretiyor. İş yeri numarası, başarılı ve başarısız işlemlerde dönülecek adresler, işlem tipi ve iş yeri anahtarı ayarlar dosyasından okunuyor. Bu değerler tutar ve taksit sayısıyla birlikte belirli bir sırada birleştiriliyor, SHA-1 ile özetleniyor ve Base64 ile kodlanıyor. Ortaya çıkan özet, bankanın isteğin değiştirilmediğini doğrulamak için kullandığı değer.

Bu bilgiler bir HTML şablonuna aktarılıyor. Şablondaki form kart numarasını, güvenlik kodunu, son kullanma tarihini ve kart tipini kullanıcıdan alıyor; diğer bütün değerleri gizli alanlar olarak taşıyor. Form doğrudan bankanın 3D ödeme adresine gönderiliyor. Para birimi Türk lirası, ödeme modeli ise 3D Pay olarak ayarlanmış.

Kart sahibi bankanın 3D Secure sayfasında doğrulamayı tamamladığında banka, sonucu iş yerinin belirlediği dönüş adresine gönderiyor. İkinci görünüm bu yanıttaki mdStatus değerini okuyor ve 0'dan 9'a kadar her durum kodunu Türkçe bir açıklamaya çeviriyor. İşlem başarılı değilse bankanın döndürdüğü hata mesajı da açıklamaya ekleniyor ve sonuç, tutar ve taksit bilgisiyle birlikte kullanıcıya gösteriliyor.

Öne çıkan özellikler

• Bankaya gönderilecek güvenlik özetinin nasıl hesaplandığını açıkça gösteriyor.
• 3D Secure işleminden dönen on durum kodunun her birinin ne anlama geldiğini Türkçe olarak açıklıyor; böylece onaylanmamış, başarılı, kart 3D Secure üyesi değil, geçersiz kart ve sistem hatası gibi durumlar kullanıcıya doğru mesajla gösterilebiliyor.
• Taksitli ve tek çekim ödemeyi aynı şablonda ele alıyor.
• Bankanın test ortamına göre hazırlandığı için gerçek kart kullanmadan denenebiliyor.

Teknik altyapı

Örnekler Python 2 ve Django ile yazıldı. Rastgele değerler için random ve string, özet için hashlib ve base64 modülleri kullanılıyor. Sayfalar Django şablonlarıyla oluşturuluyor ve adres yönlendirmeleri Django'nun URL yapılandırmasıyla tanımlanıyor. Bankanın verdiği iş yeri bilgileri kodun içine değil ayarlar dosyasına konuyor.

Durum

Kodlar 2014'te yazıldı ve depo en son 2019'da güncellendi. Python 2'ye ve Django'nun o dönemki sürümlerine göre hazırlandığı için bugün doğrudan çalıştırmak yerine akışı anlamak için referans olarak kullanılması daha doğru. Örnekte kullanılan SHA-1 özeti de günümüzde yerini daha güçlü algoritmalara bırakmış durumda.

Kullanım alanları

• EST tabanlı bir sanal POS entegrasyonuna başlayan geliştiricilerin ödeme akışını baştan sona görmesi için kullanılabilir.
• 3D Secure dönüş kodlarını kullanıcıya anlamlı mesajlar olarak göstermek isteyen her ödeme projesinde başvuru kaynağı olabilir.
• Farklı bir dil ya da çatıyla aynı entegrasyonu yazarken parametrelerin ve özet hesabının doğru sırasını kontrol etmek için işe yarar.