Python EST

Özgür Vatansever <ozgurvt@gmail.com>

Bu arabirim EST tabanlı sanal pos arabirimlerine bağlanıp, belirli metodları çalıştırmak için tasarlanmıştır.

EST Türkiye'nin e-Ticaret güvenli ödeme sistem ve hizmetleri sağlayıcısıdır. Türkiye'de e-Ticaret ödemeleri alanında faaliyet gösteren bankaların tamamına yakını bunu EST Ürün, Çözüm, Hizmetlerinden bir veya daha fazlasını kullanarak gerçekleştirmektedir.

PHP programlama diliyle geliştirilmiş aynı arabirimi kullanmak için aşağıdaki sayfayı ziyaret ediniz:

http://code.google.com/p/php-est/

Önemli not: Bu arabirim sadece aşağıdaki bankaların Sanal POS arabirimleri ile uyumludur. Diğer EST tabanlı banka arabirimleri için kullanılamamaktadır.

Akbank

İşbank

Finansbank

Halkbank

Anadolubank

KURULUM

Öncelikle;

sudo apt-get install python-setuptools

Kütüphaneyi bilgisayarınıza indirmek için 2 tane seçeneğiniz var.

SVN yardımıyla kurmak için:

- svn checkout http://python-est.googlecode.com/svn/trunk/ python-est

KULLANIMI

Önemli Not

Bu arabirimi kullanabilmeniz için "İşyeri No", "Kullanıcı adı" ve "Parola" bilgileri gereklidir. Bütün bankaların Sanal POS arabirimlerinin her biri için ayrı ayrı bu bilgileri edinmeniz gerekmektedir. Bu bilgileri edinmek istiyorsanız "destek@est.com.tr" adresine e-posta yollayınız.

Bu arabirim;

• Sipariş vermek,
• Karttan belli bir miktarı bloke etme
• Karttan bloke edilmiş miktarı çekme
• Siparişi iptal etme,
• Siparişten belli bir miktarı iade etme,
• Yapılmış bir siparişin detaylarını görebilme,
• 2 tarih arasında yapılmış tüm siparişlerin detaylarını görebilme,

fasilitelerine sahiptir.

Sanal POS sistemine yapılan bütün istekler EST sınıfı tarafından düzenlenmektedir.

EST sınıfının yukarıdaki işlemleri yapabilmesi için aşağıdaki metodlar tanımlanmıştır.

• pay() ~ Sipariş vermek yada karttan belli bir miktarın bloke işleri için bu metod çağrılır.
• postAuth() ~ Bloke edilen miktarı karttan çekmek için bu metod çağrılır.
• cancel() ~ Siparişi iptal etmek için bu metod çağrılır.
• refund() ~ Siparişten belli bir miktar para iade etmek için bu metod çağrılır.
• getDetail() ~ Bir siparişin detaylarını görmek için bu metod çağrılır.
• getDetails() ~ 2 tarih arasında yapılmış bütün siparişleri görmek için bu metod çağrılır.

Anlatırken "Akbank" Sanal POS test sunucusunu kullanacağız. Öncelikle EST sınıfını kullanarak bir api nesnesi yaratmamız gerek. Test ortamı için aşağıdaki işyeri no, kullanıcı adı ve parola bilgilerini kullanacağız.

• isyeri no: 100100000
• kullanıcı adı: AKTEST
• parola: AKTEST123

>>> from est import est
>>> est.EST?
>>> Constructor information:
>>> Definition:	est.EST(self, slug, company, name, password, debug=False)
>>> Docstring:
    @slug: is a parameter that indicates which pos service you are going to connect.
    @company: is a string value which is your company id.
    @name: is your username.
    @password: is your password.

>>> api = est.EST("akbank", "100100000", "AKTEST", "AKTEST123", debug = True)
>>> # api = est.EST("isbank", "isyerino", "kullaniciadi", "parola", debug = True)
>>> # api = est.EST("finansbank", "isyerino", "kullaniciadi", "parola", debug = True)

Eğer test sunucusu değil de gerçek ortamda çalışmak istiyorsanız debug parametresini False olarak set edin.

Sipariş verme isteği göndermemiz için pay() metodunu çağırmanız gerekmektedir. Bu metodu çağırmak için sırasıyla aşağıdaki parametreler gerekmektedir.

• kredi kartı numarası (15 yada 16 uzunlukta)
• cvv numarası (string 3 yada 4 uzunlukta)
• S.K.T ay (string 2 basamak) (örn: Ocak için '01')
• S.K.T yıl (string son 2 basamak) (örn: 2012 yılı için '12')
• Tutar (Decimal)
• Taksit (integer)
• Sipariş numarası (opsiyonel)
• Ekstra parametreler (opsiyonel)

Sipariş numarası vermeniz şiddetle tavsiye edilir. Vermezseniz POS sistemi yaptığınız siparişe sizin yerinize sipariş numarası verir.

>>> cc_num = "4848480011226398" # kart numarası
>>> cc_cvv = "000"
>>> month = "06" # Haziran
>>> year = "14"
>>> amount = Decimal("25")
>>> taksit = None # peşin
>>> order_num = "qwaszx" # sipariş numarası
>>> result, details = api.pay(cc_num, cc_cvv, month, year, amount, taksit, order_num)
>>> print result
>>> True
>>> print details
>>> {'error_msg': '',
>>>  'groupid': u'qwaszx',
>>>  'host_msg': '',
>>>  'orderid': u'qwaszx',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transaction_time': datetime.datetime(2010, 4, 19, 17, 20, 47),
>>>  'transid': u'4b5c6fb1-16dc-3000-002e-0003bafa9a61',
>>> }

Aynı sipariş numarasıyla tekrar istek yaparsak hata alacağız.

>>> result, details = api.pay(cc_num, cc_cvv, month, year, amount, taksit, order_num)
>>> print result
>>> False
>>> print details
>>> {'error_msg': u"The transaction type 'Auth' requested is not allowed for an order 
>>>   that already has a valid transaction associated with it.",
>>>  'groupid': '',
>>>  'host_msg': u'Onay alinamadi lutfen tekrar deneyiniz.',
>>>  'orderid': u'qwaszx',
>>>  'response': u'Error',
>>>  'return_code': u'99',
>>>  'transaction_time': '',
>>>  'transid': u'4b5c6fb1-16f0-3000-002e-0003bafa9a61',
>>> }

Ekstra parametrelerde fatura ve teslimat adresi ile ilgili detayları set edebilirsiniz.

Kullanabileceğiniz ekstra parametreler;

• email = string (e-posta adresi)
• ipaddress = string (ip adresi)
• billing_address_name = string (fatura adresi ismi)
• billing_address_street1 = string (f. adresi 1. adres satırı)
• billing_address_street2 = string (f. adresi 2. adres satırı)
• billing_address_street3 = string (f. adresi 3. adres satırı)
• billing_address_city = string (f. adresi şehir)
• billing_address_company = string (f. adresi şirket ismi)
• billing_address_postalcode = string (f. adresi posta kodu)
• billing_address_telvoice = string (f. adresi telefon)
• billing_address_state = string (f. adresi il/ilçe satırı)
• shipping_address_name = string (teslimat adresi ismi)
• shipping_address_street1 = string (t. adresi 1. adres satırı)
• shipping_address_street2 = string (t. adresi 2. adres satırı)
• shipping_address_street3 = string (t. adresi 3. adres satırı)
• shipping_address_city = string (t. adresi şehir)
• shipping_address_company = string (t. adresi şirket ismi)
• shipping_address_postalcode = string (t. adresi posta kodu)
• shipping_address_telvoice = string (t. adresi telefon)
• shipping_address_state = string (t. adresi il/ilçe satırı)

Sipariş numarası girmeyelim ve teslimat ve fatura adreslerine isim verelim.

>>> result, details = api.pay(cc_num, cc_cvv, month, year, amount, taksit, shipping_address_name = "Teslimat Adresi Adı", billing_address_name = "Fatura Adresi Adı")
>>> print result
>>> True
>>> print details
>>> {'error_msg': '',
>>>  'groupid': u'1271689783855-84.51.49.52-1665',
>>>  'host_msg': '',
>>>  'orderid': u'1271689783855-84.51.49.52-1665',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transaction_time': datetime.datetime(2010, 4, 19, 18, 9, 46),
>>>  'transid': u'4b5c6fb1-1760-3000-002e-0003bafa9a61'
>>> }

Kullanıcının kredi kartındaki belli bir miktara bloke koymak için typ parametresini PreAuth olarak göndermeniz gerekmektedir.

>>> result, details = api.pay(cc_num, cc_cvv, month, year, amount, taksit, orderid = "abcdef", typ = "PreAuth")
>>> print result
>>> True
>>> print details
>>> {'auth_code': u'852468',
>>>  'error_msg': '',
>>>  'groupid': u'abcdef',
>>>  'host_msg': u'Onay',
>>>  'orderid': u'abcdef',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transaction_time': datetime.datetime(2010, 5, 6, 3, 44, 3),
>>>  'transid': u'10126-DsDJ-1-0341'
>>> }

Bloke koyduğumuz miktarı kullanıcının kartından çekmek için postAuth() metodunu çekmek istediğiniz miktar ile çağırmanız gerekmektedir.

>>> result, details = api.postAuth(amount, "abcdef")
>>> print result
>>> True
>>> print details
>>> {'auth_code': u'950599',
>>>  'error_msg': '',
>>>  'groupid': u'abcdef',
>>>  'host_msg': '',
>>>  'orderid': u'abcdef',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transaction_time': datetime.datetime(2010, 5, 6, 3, 48, 40),
>>>  'transid': u'10126-DwoI-1-0347'
>>> }

Siparişi yada yaptığınız postAuth isteğini iptal etmek için cancel() metodu çağrılmalıdır. Sipariş numarası parametre olarak verilmelidir.

>>> result, details = api.cancel("abcdef")
>>> print result
>>> True
>>> print details
>>> {'error_msg': '',
>>>  'groupid': 'abcdef',
>>>  'host_msg': '',
>>>  'host_ref_num': u'123456789012',
>>>  'orderid': u'abcdef',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transid': u'4b5c6fb1-16dc-3000-002e-0003bafa9a61'
>>> }

Var olmayan ya da daha önceden iptal edilmiş bir siparişi tekrar iptal etmeye çalışılırsa sunucudan aşağıdaki gibi bir cevap alınır.

>>> result, details = api.cancel("3efesfsdfsdfds")
>>> print result
>>> False
>>> print details
>>> {'error_msg': u"Did not find a unique, qualifying transaction for Order
>>>  '3efesfsdfsdfds'.",
>>>  'groupid': '',
>>>  'host_msg': u'Girilen siparis numarasina ait uygun islem bulunamadi.',
>>>  'host_ref_num': '',
>>>  'orderid': u'3efesfsdfsdfds',
>>>  'response': u'Error',
>>>  'return_code': u'99',
>>>  'transid': ''
>>> }

Siparişten belli bir miktarın tutarının müşterinin kartına geri yüklenmesi işlem için refund() metodu çağrılmalıdır.

>>> result, details = api.refund(amount = decimal.Decimal("10"), orderid = "1271689783855-84.51.49.52-1665")
>>> print result
>>> True
>>> print details
>>> {'error_msg': '',
>>>  'groupid': u'1271689783855-84.51.49.52-1665',
>>>  'host_msg': '',
>>>  'host_ref_num': u'123456789012',
>>>  'orderid': u'1271689783855-84.51.49.52-1665',
>>>  'response': u'Approved',
>>>  'return_code': u'00',
>>>  'transid': u'4bc5525c-6798-3000-002d-0003bafa9a61',
>>> }

Eğer sipariş tutarından daha büyük bir tutar iptal edilmeye çalışırsa aşağıdaki cevap alınır.

>>> result, details = api.refund(amount = decimal.Decimal("9999"), orderid = "1271689783855-84.51.49.52-1665")
>>> print result
>>> False
>>> print details
>>> {'error_msg': u'Credit cannot be performed because the credit amount is greater than >>>   the sum of settled and captured transactions.',
>>>  'groupid': '',
>>>  'host_msg': u'Iade tutari satis tutarindan buyuk olamaz.',
>>>  'host_ref_num': '',
>>>  'orderid': u'1271689783855-84.51.49.52-1665',
>>>  'response': u'Error',
>>>  'return_code': u'99',
>>>  'transid': u'4bc5525c-679c-3000-002d-0003bafa9a61'
>>> }

Eğer refund metodu ile yaptığınız iade isteğini iptal etmek istiyorsanız iade işleminden size cevap olarak gönderilen transid ve orderid değerlerini cancel() metoduna göndermeniz gerekmektedir.

>>> result, details = api.cancel(orderid = '1271689783855-84.51.49.52-1665', transid = '4bc5525c-679c-3000-002d-0003bafa9a61')
>>> print result
>>> True

İptal(cancel) ile İade(refund) Arasındaki Farklar

Bilindiği gibi sanal poslarda da gerçek pos hesapları gibi gün sonu kavramı vardır. Gün sonu kavramı; gün içinde pos ile ilgili yapılan işlemlerin (para çekimi(pay) ve para iadesi(refund) gibi) gün sonunda pos sahibinin banka hesabına aktarılması demektir.

Siparişin iptal(cancel) işlemi gün sonu gelmeden sadece aynı gün içinde yapılabilir. Önceki güne ait siparişler iptal edilemezler. Önceki güne ait siparişler ancak refund() metodu ile siparişin tutarı girilerek iade edilirler.

Eğer sipariş cancel() metodu ile iptal edilirse; siparişin yapıldığı ve iptal edildiği gibi detaylar kart sahibinin ektresinde görünmez. Eğer refund() metodu ile iade yapılırsa iade işlemi kart sahibinin ekstresine yansır. Bankaların çoğunda gün sonu akşam saat 22:00 dir. Fakat bunu bankalar kendilerine göre değiştirebilirler.

Daha önceden verilmiş bir siparişin detayı öğrenilmek isteniyorsa getDetail() metodu kullanılmalıdır. Bu metoda sipariş numarası parametre olarak verilir.

>>> result = api.getDetail("1271689783855-84.51.49.52-1665")
>>> print result
>>> {'amount': Decimal('1.00'),
>>>  'error_msg': u'00:1271689783855-84.51.49.52-1665 numarali siparise ait kayit 
>>>   bulundu',
>>>  'host_ref_num': u'123456789012',
>>>  'num_code': u'01800099999999',
>>>  'orderid': '1271689783855-84.51.49.52-1665',
>>>  'return_code': u'00',
>>>  'transaction_time': datetime.datetime(2010, 4, 19, 15, 56, 35),
>>>  'transid': u'4bc5525c-67a0-3000-002d-0003bafa9a61',
>>> }

Belirli 2 tarih arasında yapılmış siparişler listelenmek isteniyorsa getDetails() metodu kullanılmalıdır. Parametre olarak başlangıç ve bitiş tarihleri verilmelidir. Verilmezse son 15 günde yapılmış siparişler listelenir.

>>> now = datetime.datetime.now()
>>> td = datetime.timedelta(days = 1)
>>> yesterday = now - td
>>> result = api.getDetails(yesterday, now)
>>> {'details': [<est.est.OrderDetail object at 0x263edd0>,
>>>              <est.est.OrderDetail object at 0x263ee90>,
>>>              <est.est.OrderDetail object at 0x263ef90>,
>>>              <est.est.OrderDetail object at 0x2661050>,
>>>              <est.est.OrderDetail object at 0x26610d0>,
>>>              <est.est.OrderDetail object at 0x2661150>,
>>>              <est.est.OrderDetail object at 0x26612d0>,
>>>              <est.est.OrderDetail object at 0x2661950>],
>>> }
>>> details = result.get("details")
>>> siparis = details[0]
>>> print siparis.type
>>> 'SATIS'
>>> siparis.amount
>>> Decimal("99.90")
>>> print siparis.installment
>>> 0
>>> siparis.orderid
>>> "qwaszx"
>>> siparis.date
>>> '2010-04-19 03:09:00'