PayNet Sanal POS Teknik Dökümanı PAYNET İşlemleri PAYNET sistemi, Arena Bilgisayar A.Ş. nin, bayilerine artı değer olarak sunduğu bir online ödeme sistemidir. Bu sistem v1.0 itibariyle, sadece kredi kartları ile ödeme yapılabilmesine olanak sağlamaktadır. Sistemin normal bir POS cihazı gibi satış ve satış iptal işlemlerini yapması öngörülmektedir. Paynet webservise lerine https://www.paynet.com.tr/connact/iodeme.asmx adresinden ulaşılabilir. 3.5.1. PAYNET Sistemi Webservis Tanımı PAYNET webservisi şu iş surecine göre düzenlenmiştir: Bir bayinin birden fazla banka ile sözleşmesi olabilir. GetBanklist webservisi bayinin sozleşme imzaladığı bankaların listesini gönderir. Dönüş tipi bank veri tipinde bir listedir, yapısı aşagıda belirtilmiştir. Bankanın tanıtıcısı bankid dir. Bu tanıtıcı ile daha sonra GetBankDetails webservisi ile banka detay bilgilerine ulaşılır. GetBankDetails webservisi ile banka detay bilgilerine ulaşılır. Bir bayinin bir banka ile birden fazla antlaşması olabilir. Geri dönüş tipi agentbankdetail veri tipinde bir listedir. Daha sonra bu bilgiler Sales webservisinde satış işlemi için kullanılacak degerleri içerir. Sales webservisi GetBankDetails webservisinden dönen bankid ve posid değerlerini alarak çalışır. Sales Satış işlemini gerçekleştirir ve başarılı işlemde provizyon ve referans kodu, hata durumunda ise hata kodu ve açıklamasını döndürür. Dönüş veritipi xactresult tipinde olacaktır. SoapHeader ında AuthenticationInfo veri yapısı doldurulmalı. Herhangi bir webservis çagrılırken AuthenticationInfo veri yapısı içindeki agentid ve username değişkenleri doldurulup gönderilir. Dönen degerde de yine SoapHeader ında AuthenticationInfo veri yapısı içindeki authenticated degeri kontrol edilmelidir, bu alan true ise yetkiniz var false ise yetkiniz yok demektir. Kullanılacak webservislerin Soap tanımlarına aşagıdaki adreslerden ulaşılabilir. GetBanklist : https://www.paynet.com.tr/connact/iodeme.asmx?op=getbanklist GetBankDetails: https://www.paynet.com.tr/connact/iodeme.asmx?op=getbankdetails Sales : https://www.paynet.com.tr/connact/iodeme.asmx?op=sales Eğer canlı sisteme baglanmadan önce test sistemimize bağlanarak test yapmak isterseniz, host dosyanıza 194.50.84.38 test.iodeme.com satırını ekleyip test sistemine http://test.iodeme.com/iodeme.asmx adresinden erişebilirsiniz. Test sisteminden yararlanmak için müşteri hizmetleri ile temasa geçip test sistemi için gerekli tanımlarınızın yapılmasını isteyiniz. Gerekli tanımlarınız yapıldıktan sonra agentid olarak bayi kodunuzu, username olarak da CONNACT yollayarak testlerinizi yapabilirsiniz. (Daha fazla bilgi için bkz. A.2 Paynet ve Connact Entegrasyonu İpuçları) Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 1 -
3.5.2. PAYNET Sistemi Webservis Sınıfları AuthenticationInfo System.Web.Services.Protocols.SoapHeader dan türetilmiş, authentication bilgilerini bulunduran sınıftır. Webservisin her metodu çağrılırken gönderilmeli ve authenticated alanı kontrol edilmeden dönen değerlere bakılmamalıdır. agentid string Bayi kodu username string Kullanıcı adı authenticated Bool (ReadOnly) Eğer bilgiler doğru ise true döner. xactparam Satış işlemi parametreleri için kullanılan sınıftır. Birden çok karttan satış işlemi yapılabilmesi için dizi olarak kullanılmaktadır. cardholdername string Kart sahibinin adı (Peşin=0) cardexpiredate DateTime Kart geçerlik sonu cvc string CVV kodu xactresult Yapılan işlem sonucunu döndüren sınıftır. type xacttype İşlem tipi authorizationcode string Eğer satış işlemi ise, provizyon kodu, diğer durumlarda boş referencecode string Eğer satış işlemi ise, referans kod, diğer durumlarda boş error_code string Hata olduysa, hata kodu error_text string Hata açıklaması result_text string İşlem başarılı ise OK, değilse ERROR cardholder string Kart sahibinin adı expdate DateTime Kart geçerlik tarihi Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 2 -
bank Banka bilgileri için kullanılan sınıftır. ID string Banka tanıtıcısı Name string Banka adı phone string Müşteri temsilcisi telefon numarası representative string Müşteri temsilcisi adı soyadı email string Müşteri temsilcisi elektronik posta adresi agentbankdetail Bayinin banka detay bilgileri için kullanılan sınıftır. merchantid string merchantid bilgisi terminalid string terminalid bilgisi additionalinfo NameValue[] Bankaya özel ek bilgiler instalmentitem Taksit bilgileri için kullanılan sınıftır. ratio float Uygulanacak vade farkı % expiredate DateTime Vade farkı geçerlik sonu bankinstalmentitem Banka bazında uygulanacak taksit bilgileri için kullanılan sınıftır. instalments instalmentitem[] Banka için tanımlanmış taksit bilgileri bankinstalmentcollection Bayinin sözleşme imzaladığı bankalarla çalışabileceği taksit seçenekleri için kullanılan sınıftır. this[] bankinstalmentitem Default indexer. Gerek itemindex bazında gerekse banka tanıtıcısı bazında erişilebilir. Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 3 -
xactitem Bayinin iodeme sistemi üzerinde gerçekleştirdiği işlemler için kullanılan sınıftır. date DateTime İşlemin gerçekleştiği tarih-saat type xacttype İşlem tipi bankname string Banka adı cardholder string Kart sahibinin adı Username string İşlemi gerçekleştiren kullanıcı (yeni) campaign_stext string Kampanyalı satış işlemi ise kampanya kısa metni (yeni) xactdetail iodeme sistemi üzerinden gerçekleştirilmiş bir işlemin detay bilgileri için kullanılan sınıftır. date DateTime İşlemin gerçekleştiği tarih-saat bankname string Banka adı cardholder string Kart sahibinin adı authorizationcode string Provizyon kodu referencecode string Referans kodu expdate DateTime Kart geçerlik tarihi NameValue Bir tanıtıcı ve bir değerden oluşan basit bir sınıftır. name string Tanım value string Değer iodeme Webservis çağrılarının yapıldığı ana sınıftır. AuthenticationHeader AuthenticationInfo Yetkilendirme bilgileri Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 4 -
campaignitem Kampanya metni, geçerlilik süreleri için kullanılan sınıftır. campaignid int Kampanya tanıtıcısı campaign_text string Kampanya metni datefrom DateTime Kampanya başlanıç tarihi dateto DateTime Kampanya bitiş tarihi owncampaign bool Bayinin yarattığı kampanya campaign_stext string Kampanya kısa metni campaignratio Kampanya oranları için kullanılan sınıftır. ID int Kampanya oranı tanıtıcısı campaignid int Kampanya tanıtıcısı bankid string Kampanya banka tanıtıcısı ratio decimal Kampanya taksit oranı campaigndetail Kampanya bilgileri için kullanılan sınıftır. info campaignitem Kampanya bilgisi ratios campaignratio[] Kampanya oranları koiqueryparam Yalnızca YKB-WorldCard a özel olan Vadaa seçeneklerini sorgulamak için kullanılacak sınıftır. Sınıf Üyeleri Veritipi Açıklama Cardno string Kart numarası koiinfo Yalnızca YKB-WorldCard a özel olan Vadaa seçenekleri bilgileri için kullanılan sınıftır. Sınıf Üyeleri Veritipi Açıklama Code string Vadaa seçeneği kodu message string Vadaa mesajı description string Vadaa türü Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 5 -
koiqueryresult sınıftır. Yalnızca YKB-WorldCard a özel olan Vadaa seçenekleri sorgulandığında, sorgu sonucu için kullanılan result_text string İşlem başarılı ise OK, değilse ERROR error_code string Hata olduysa hata kodu error_text string Hata açıklaması Koi koiinfo[] Vadaa seçenekleri koisalesparam Yalnızca YKB-WorldCard a özel olan Vadaa seçeneklerini kullanarak satış işlemi yapmak için kullanılan sınıftır. koicode int Vadaa seçeneği kodu campaignid int Kampanyalı satış ise kampanya tanıtıcısı, değilse 0 (sıfır) bankid String Banka tanıtıcısı posid String POS tanıtıcısı cardholdername string Kart sahibinin adı cardexpriredate DateTime Kart geçerlilik sonu cvc string CVV kodu email string Kart sahibinin e-maili phone string Kart sahibinin telefonu 3.5.3. PAYNET Sistemi Webservis Metodları Sales Satış işlemini gerçekleştirir ve başarılı işlemde provizyon ve referans kodu, hata durumunda ise hata kodu ve açıklamasını döndürür. Dönüş veritipi xactresult tipinde olacaktır. xactparams xactparam[] İşlem yapılacak kart bilgileri Reversal Daha önce yapılmış olan bir satış işlemini iptal eder. Dönüş veritipi xactresult tipinde olacaktır. Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 6 -
GetBankList AuthenticationHeader da bilgisi gönderilen bayinin sözleşme imzaladığı bankaların listesini döndürür. Dönüş veritipi bank dizisi şeklinde olacaktır. GetBankDetails Belirtilen banka için tanımlanmış olan bayiye özel bilgileri döndürür. Dönüş veritipi agentbankdetail dizisi şeklinde olacaktır. xactparam, koiqueryparam, koisalesparam sınıflarının posid alanına, bu metod yardımıyla ilgili banka için elde edilen banka bilgileri arasında yer alan posid değeri verilmelidir. GetInstalmentOptions AuthenticationHeader da bilgisi gönderilen bayinin sözleşme imzaladığı bankalar için tanımlı olan taksit ve oran bilgilerini döndürür. Dönüş veritipi bankinstalmentcollection şeklinde olacaktır. getdefault bool true ise Arena nın tanımlı oranları, false ise varsa bayinin özel oranları GetTransactionList Bayinin iodeme sistemi üzerinden gerçekleştirdiği işlemleri xactitem dizisi şeklinde döndürür. date1 DateTime Tarih 1 date2 DateTime Tarih 2 bankid string Banka Tanıtıcısı cardholder string Kart sahibinin adı GetTransactionDetail iodeme sistemi üzerinden gerçekleşen işlemin detay bilgilerini döndürür. Dönüş veritipi xactdetail şeklinde olacaktır. Paynet Vadaa Metodları koiquery Yalnızca YKB-WorldCard a özel olan Vadaa seçeneklerini sorgulamak için kullanılır. Dönüş değeri koiqueryresult tipindedir. Param koiqueryparam İşlem bilgileri Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 7 -
koisales Yalnızca YKB-WorldCard a özel olan Vadaa seçeneklerini kullanarak satış işlemi yapmak için kullanılır. Dönüş değeri xactresult tipindedir. Param koisalesparam İşlem bilgileri A.1 HATA YAKALAMA İşlem sırasında bir hata oluşursa CONNACT geriye TABLO : 14 de belirtilen Schema ya Uygun bir XML döndürür. <?xml version="1.0" encodõng="utf-8"?> <xs:schema id="sondamsjschema" targetnamespace="http://<host_adres>/sondamsjschema.xsd" elementformdefault="qualified" xmlns="http://<host_adres>/sondasjschema.xsd" xmlns:mstns="http://<host_adres>/msjschema.xsd" xmlns:xs="http://www.w3.org/2001/xmlschema"> <xs:element name="error"> <xs:complextype> <xs:sequence> <xs:element name="type" type="xs:string" /> <xs:element name="text" type="xs:string" /> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> TABLO 14 : SondaMsjSchema.xsd Sahaların Açıklamaları : TYPE : Hatanın Tipi Alabilecegi Degerler : OK, ERROR, WARNING, UNAUTHORISED, AUTHORISED, INVALIDDATA, SIMULATIONERROR, INVALIDPRODUCTS. TEXT : Hatanın açıklaması. Versiyon 2.05 Arena Bilgisayar A.Ş. 2007 tüm hakları saklıdır. - 8 -