-
Sanal POS
Sanal POS İşlemleri Genel Kavramlar
Garanti Sanal POS, internet üzerinden yapılan satışlarda kredi kartı ile ödeme alınabilmesi için oluşturulan güvenli bir ödeme çözümüdür.
Üye işyerleri, mağazalarında internet üzerinde bir şube açıp, Garanti Sanal POS ile, onu hiç kapanmayan bir satış platformu haline gelebilir. Böylece hem müşteri sayıları, hem de cironun artırılmasına katkı sağlanır.
Garanti Sanal POS altında genel olarak aşağıdaki işlemler gerçekleştirilmektedir:
- Satış İşlemleri
- Ortak Ödeme Sayfası İşlemleri
- İptal İşlemleri
- İade İşlemleri
- Kapama İşlemleri
- Sorgulama İşlemleri
Bu doküman içerisinde, üye işyerlerinin Garanti Sanal POS altında 3D’siz Ek Alan işlemlerinin sağlanabilmesi için gerekli olan adımlar, her bir adım içerisinde yapılması gereken işlemler ve gönderilen işlem istekleri ve alınan cevap mesajlarının yapıları anlatılmaktadır.
Sanal POS Ek Alan İşlemleri
Sanal POS istek yapısı içerisinde, farklı ihtiyaçlata uygun şekilde, farklı ek alanlar ile istek yapısı değiştirilebilir. Aşağıdaki başlıklarda bu ek alanlar ve amaçları hakkında kısaca bilgi verilmiştir.
1. Adres Gönderimi:
Adres bilgileri işlem sırasında SanalPoS tarafına gönderilebilir. Gönderilen bilgiler sipariş detay sayfalarından bilgi amaçlı gösterilir.
2. Ürün Bilgisi Gönderimi:
Satın alma sırasında satılan ürüne ait bilgiler işlemle birlikte sanal posa gönderilebilir. İşlem detaylarında ve ürün rapor sayfalarında bu durumda ürün bilgilerinin görüntülenmesi sağlanır.
3. Özel alan Gönderimi:
İşlem sırasında alınacak bazı özel bilgilerin sanal pos ekranlarında ve sanal postan alınan dokümanlarda gözükmesini sağlayan yapıdır.
Özel alanlardan 1. özel alan Garanti Bankasına yollanılmaktadır. Bu alan banka tarafından alınan raporlarda gösterilir.
İşyeri tanımlarında yapılan değişiklik ile bu alanda gönderilen değerlerin kart dönem içi işlemler ve kart ekstrelerine işyeri adı alanında çıkması sağlanabilir.
Özel alanların kullanımı için işyeri admin kullanıcısının özel alan tanımlarından kullanılacak özel alanları aktif hale getirmesi gereklidir. Aktif edilmeden gönderilen özel alanlar hataya sebep olacaktır. 1 nolu özel alanın banka tarafına gitmesi isteniyorsan banka tarafında gözüksün ibaresi işaretlenmelidir.
Özel alanların listeleme ekranlarında gözükmesi için kullanıcı tarafından özel alan seçim sayfasından seçilmesi gerekmektedir. Seçilen özel alanlar listeleme sayfalarının sağ tarafından birer sütun olarak gözükür.
3D Kavramı
3D Secure , PoS üzerinde kart sahiplerinin şifre ile doğrulandığı uygulamanın, SanalPoS üzerinde yapılan halidir. Kart sahibi, işlemde şifre kullanması için kart bankasına ait doğrulama ekranlarına yönlendirilir. Kart sahibi bu ekranlar üzerinden bankasının istediği bilgileri girerek, gerçekten kullanılan kartın kendisine ait bir kart olduğunu gösterir.
Doğrulama sonucunda, doğrulama durumu işyeri bankaya (işyerine) döndürülür. Daha sonra 3D bilgilerinin durumuna göre provizyon işleminin gerçekleştirilmesi ya da işlemin sonlandırılması gerçekleştirilir.
3D Secure Master, Visa ve American Express(Amex) kartların desteklediği bir uygulamadır. 3D model (aşağıda işyeri modelleri hakkında bilgi verilmektedir) kullanan işyerlerinin Mastercard, Visa ve Amex dışındaki kartlar için 3D doğrulaması gerçekleştirmeden direk provizyona gelmeleri gerekmektedir. 3D secure desteklenmediği için bu tür işlemlerde Fraud sorumluluğu işyerine aittir. İşyeri kendisini koruyacak önlemleri almalıdır.
Sanal POS 3D'siz İşlemler
Gerçekleşen işlemin provizyon akışı sırasında herhangi bir 3D secure aşamasına değmeden sonuçlanmasıdır. Bu işlem tipinde müşterinin “ben yapmadım” itirazları chargeback talebine dönüşür. İşyerinden işlemin müşteri tarafından yapıldığına yönelik kanıtlar talep edilerek chargeback süreci değerlendirilir. 3D’li işlemlerde başarılı doğrulaması yapılan işlemlerde işlemi “ben yapmadım” talepleri banka tarafında sonlandırılır.
Test / Prod Ortam Seçimleri:
Sanal POS Satış işlemleri için, üye işyeri tarafından 2 farklı yöntem ile ilerlenmesi mümkündür. Üye işyeri dilerse yapacağı tüm geliştirmeleri Test ortamında yapabilir. Alternatif olarak doğrudan yayın ortamında da bu işlemler için gerekli geliştirmeler yapılabilir.
Üye işyeri tarafından seçilecek yönteme göre, Sanal POS satış işlemlerine başlamadan önce aşağıdaki başlıklardan uygun olana göre ilk işlemlerin yapılması gerekmektedir:
Yapılacak çalışmaların test ortamında yürütülmesi durumunda, aşağıda belirtilen ön tanımlı değerler oldugu gibi kullanılabilir:
| Parametre | Değer |
|---|---|
| MerchantID | 7000679 |
| ProvUserID | PROVAUT / PROVRFN / PROVOOS |
| ProvisionPassword | 123qweASD/ |
| TerminalID | 30691297 |
| StoreKey | 12345678 |
Test ortamında yapılacak çalışmalarda "https://sanalposprovtest.garantibbva.com.tr/servlet/gt3dengine" url'i kullanılacaktır.
Test ortamında yapılan işlemlerin takip edilebileceği ve görüntülenebileceği panele bu adresten erişebilirsiniz.
| Değişken | Değer |
|---|---|
| Kullanıcı Adı | 99999999999 |
| Parola | Destek05 |
| Şifre | 147852 |
Not: Parola işlemlerinde hata alınması durumunda 2.kez deneme yapılmadan önce lütfen Bize Soru Gönderin formu ile bilgi veriniz.
Test ortamında kullanılabilecek tüm test kartlarının listesine bu sayfadan ulaşabilirsiniz.
Bu yöntem ile ilerlendiğinde, üye işyeri tarafından ilk adım olarak kurulumda kullanılacak olan şifreler (“PROVAUT”,“PROVOOS”, “PROVRFN” ve “3D” (storekey) şifreleri) Sanal POS İlk Adımlar dokümanı içerisinde belirtildiği şekilde sanal pos yönetim panelinden oluşturmalıdır.
Sonraki adımlarda, bu şekilde oluşturulan şifre ve hesaplar kullanılacaktır.
PROD ortamında yapılacak çalışmalarda "https://sanalposprov.garanti.com.tr/servlet/gt3dengine" url'i kullanılacaktır.
Hash Algoritması
Bu doküman içerisinde, birçok işlem tipi altında kullanılan ve istek mesajı içerisinde <HashData> şeklinde yer alan etiket için gerekli olan verinin nasıl oluşturulacağını adım adım anlatılmaktadır.
İstek mesajları içerisinde yer alan <HashData> etiketi; kullanıcıya ait şifre doğrulamasının yapılmasını sağlayan alandır. Hash oluşturma detayları aşağıda ayrıca anlatılmaktadır.
Yeni SanalPoS uygulamasında, terminale ait şifrenin açık şekilde dolaşmasının engellenmesi için HASH yapısı kullanılmaktadır.
Hash hesabı:
- Hashedpassword bilgisinin hesaplanmasında SHA1
- Hashvalue değerinin hesaplanmasında SHA512 algoritması kullanılmaktadır.
Hash hesaplamasında, İki parçalı HASH yapısı kullanılmaktadır. İlk aşamada provizyon şifresinin, terminal numarası ile yanyana getirilmesi ile SHA1 algoritması kullanılarak hashedpassword değerinin elde edilmesi sağlanacaktır.
Hash oluşturmak için gerekli olan işlemler, aşağıda farklı programlama dilleri için sunulmuştur:
public static string Sha1(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA1CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string Sha512(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA512CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string GetHashData(string provisionPassword, string terminalId, string orderId, int installmentCount, string storeKey, ulong amount, int currencyCode, string successUrl, string type, string errorUrl) {\n var hashedPassword = Sha1(provisionPassword + \"0\" + terminalId);\n return Sha512(terminalId + orderId + amount + currencyCode + successUrl + errorUrl + type + installmentCount + storeKey + hashedPassword).ToUpper();\n}
Public Shared Function Sha1(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA1CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function Sha512(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA512CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function GetHashData(provisionPassword As String, terminalId As String, orderId As String, installmentCount As Integer, storeKey As String, amount As ULong, currencyCode As Integer, successUrl As String, type As String, errorUrl As String) As String\n Dim hashedPassword As String = Sha1(provisionPassword & \"0\" & terminalId)\n Return Sha512(terminalId & orderId & amount & currencyCode & successUrl & errorUrl & type & installmentCount & storeKey & hashedPassword).ToUpper()\nEnd Function
public static String calculateHash(String data, String algorithm, String charset) throws UnsupportedEncodingException, NoSuchAlgorithmException {\n\tMessageDigest md = MessageDigest.getInstance(algorithm);\n\tbyte[] databytes = data.getBytes(charset);\n\t\n\tmd.update(databytes);\n byte[] hashBytes = md.digest();\n \n return byteArray2HexaDecimal(hashBytes);\n}\n\npublic static String sha1(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-1\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String sha512(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-512\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String getHashData(String provisionPassword, String terminalId, String orderId, int installmentCount, String storeKey, long amount, int currencyCode, String successUrl, String type, String errorUrl) throws NoSuchAlgorithmException {\n String hashedPassword = sha1(provisionPassword + \"0\" + terminalId);\n return sha512(terminalId + orderId + amount + currencyCode + successUrl + errorUrl + type + installmentCount + storeKey + hashedPassword).toUpperCase();\n}
private function GenerateSecurityData($terminalId)\n {\n $password = \"password\";\n $data = [\n $password,\n str_pad((int)$terminalId, 9, 0, STR_PAD_LEFT)\n ];\n $shaData = sha1(implode('', $data));\n return strtoupper($shaData);\n }\n\n public function GenerateHashData()\n {\n $orderId = \"order_id\"; //must be uniqe\n $terminalId = \"terminal_id\"; //must be integer\n $amount = \"100\"; //amount\n $currencyCode = \"currency_code\"; //must be int\n $storeKey = \"\";\n $installmentCount = 0;\n $successUrl = \"https://localhost/success\";\n $errorUrl = \"https://localhost/error\";\n $type = \"\",\n $hashedPassword = GenerateSecurityData($terminalId); \n return strtoupper(hash('sha512', $terminalId . $orderId . $amount . $currencyCode . $successUrl . $errorUrl . $type . $installmentCount . $storeKey . $hashedPassword));\n }
Sanal POS Satış 3D'li Tüm İşlem Tipleri İçin Genel Form Yapısı
<form method=\"post\" role=\"form\" action=\"https://sanalposprovtest.garantibbva.com.tr/servlet/gt3dengine\">\n\t<!--Value alanı test ortamı için: TEST üretim ortamı için: PROD olmalıdır.-->\n\t<input type=\"hidden\" name=\"mode\" id=\"mode\" value=\"TEST\" />\n\t<!--API Sürümü-->\n\t<input type=\"hidden\" name=\"apiversion\" id=\"apiversion\" value=\"512\" />\n\t<!--Güvenlik Düzeyi (Value değerleri: \"CUSTOM_PAY\", \"3D_PAY\", \"3D_FULL\", \"3D_HALF\" seçeneklerinden birisi olmalıdır.)-->\n\t<input type=\"hidden\" name=\"secure3dsecuritylevel\" id=\"secure3dsecuritylevel\" value=\"3D_PAY\" />\n\t<!--Terminal Provision User ID-->\n\t<input type=\"hidden\" name=\"terminalprovuserid\" id=\"terminalprovuserid\" value=\"PROVAUT\" />\n\t<!--Terminal User ID-->\n\t<input type=\"hidden\" name=\"terminaluserid\" id=\"terminaluserid\" value=\"GARANTI\" />\n\t<!--Terimal Merchant ID-->\n\t<input type=\"hidden\" name=\"terminalmerchantid\" id=\"terminalmerchantid\" value=\"7000679\" />\n\t<!--Terminal ID-->\n\t<input type=\"hidden\" name=\"terminalid\" id=\"terminalid\" value=\"30691297\" />\n\t<!--Sipariş ID (Benzersiz bir işlem numarası olmalıdır.)-->\n\t<input type=\"hidden\" name=\"orderid\" id=\"orderid\" value=\"ef43ef579b97484d9f67d445e4b15b93\" />\n\t<!--Başarılı İşlem Dönüş Bağlantısı-->\n\t<input type=\"hidden\" name=\"successurl\" id=\"successurl\" value=\"oospayment/result\" />\n\t<!--Başarısız İşlem Dönüş Bağlantısı-->\n\t<input type=\"hidden\" name=\"errorurl\" id=\"errorurl\" value=\"oospayment/result\" />\n\t<!--Müşteri E-Posta Adresi-->\n\t<input type=\"hidden\" name=\"customeremailaddress\" id=\"customeremailaddress\" value=\"eticaret@garanti.com.tr\" />\n\t<!--Müşteri IP Adresi-->\n\t<input type=\"hidden\" name=\"customeripaddress\" id=\"customeripaddress\" value=\"192.168.0.1\" />\n\t<!--Firma Adı-->\n\t<input type=\"hidden\" name=\"companyname\" id=\"companyname\" Value=\"GARANTI TEST\" />\n\t<!--Dil Bilgisi-->\n\t<input type=\"hidden\" name=\"lang\" id=\"lang\" Value=\"tr\" />\n\t<!--İşlem Zamanı (UTC)-->\n\t<input type=\"hidden\" name=\"txntimestamp\" id=\"txntimestamp\" value=\"2023-04-30T11:31:53Z\" />\n\t<!--Yenileme Süresi-->\n\t<input type=\"hidden\" name=\"refreshtime\" id=\"refreshtime\" value=\"1\" />\n\t<!--Güvenli Hash Anahtarı (Bu alana hash algoritasmasından gelen değer girilmelidir.)-->\n\t<input type=\"hidden\" name=\"secure3dhash\" id=\"secure3dhash\" value=\"Hesaplanan hash değeri eklenmelidir.\" />\n\t<!--İşlem Yapılan Tutar-->\n\t<input type=\"hidden\" name=\"txnamount\" id=\"txnamount\" value=\"100\" />\n\n\t<!--İşlem Tipi-->\n\t<!--Ön otorizasyon işlem tipinde value değeri: \"preauth\"-->\n\t<!--Bonus kullanımında işlem tipinde value değeri: \"preauth\"-->\n\t<!--Tekrarlı satış işlem tipinde value değeri: \"preauth\"-->\n\t<!--DCC işlem tipinde value değeri: \"dccinq\"-->\n\t<!--Ortak Kart işlem tipinde value değeri: \"commercialcard\"-->\n\t<!--Futures Sale işlem tipinde value değeri: \"extendedcredit\"-->\n\t<input type=\"hidden\" name=\"txntype\" id=\"txntype\" value=\"sales\" />\n\t<!--Para Birimi value değerleri: TR: \"949\" | USD: \"840\" | EURO: \"978\" | GBP: \"826\" | JPY: \"392\"-->\n\t<input type=\"hidden\" name=\"txncurrencycode\" id=\"txncurrencycode\" value=\"949\" />\n\t<!--Taksit Sayısı (Taksit gerekmeyen işlemlerde: \"\" girilmelidir.)-->\n\t<input type=\"hidden\" name=\"txninstallmentcount\" id=\"txninstallmentcount\" value=\"\" />\n\n\t<!--EK Parametreler Bu Alana Eklenebilir Başlangıç _____________________________ -->\n\t\n\t<!--Bonus Kullanım Parametreleri Başlangıç-->\n\t<input type=\"text\" name=\"txnrewardcount\" value=\"1\"><br>\n\t<input type=\"text\" name=\"txnrewardtype1\" value=\"BNS\"><br>\n\t<input type=\"text\" name=\"txnrewardusedamount1\" value=\"100\"><br>\n\t<!--Bonus Kullanım Parametreleri Bitiş-->\n\n\t<!--Firma Bonus Kullanım Parametreleri Başlangıç-->\n\t<input type=\"text\" name=\"txnrewardcount\" value=\"1\"><br>\n\t<input type=\"text\" name=\"txnrewardtype1\" value=\"FBB\"><br>\n\t<input type=\"text\" name=\"txnrewardusedamount1\" value=\"100\"><br>\n\t<!--Firma Bonus Kullanım Parametreleri Bitiş-->\n\n\t<!--Bonus ve Firma Bonus Kullanım Parametreleri Başlangıç-->\n\t<input type=\"text\" name=\"txnrewardcount\" value=\"2\"><br>\n\t<input type=\"text\" name=\"txnrewardtype1\" value=\"BNS\"><br>\n\t<input type=\"text\" name=\"txnrewardusedamount1\" value=\"100\"><br>\n\t<input type=\"text\" name=\"txnrewardtype2\" value=\"FBB\"><br>\n\t<input type=\"text\" name=\"txnrewardusedamount2\" value=\"100\"><br>\n\t<!--Bonus ve Firma Bonus Kullanım Parametreleri Bitiş-->\n\n\t<!--Sabit Tekrarlı Satış Başlangıç-->\n\t<input type=\"hidden\" name=\"recurringtype\" value=\"R\" />\n\t<input type=\"hidden\" name=\"totalpaymentnum\" value=\"5\" /> <!--Tekrar Sayısı-->\n\t<input type=\"hidden\" name=\"frequencytype\" value=\"M\" /> <!--Ay: (M), Gün: (D), Hafta: (W)-->\n\t<input type=\"hidden\" name=\"frequencyinterval\" value=\"1\" /> <!--1 Tekrar Frekans (M/D/W)-->\n\t<input type=\"hidden\" name=\"startdate\" value=\"20221213\" /> <!--YYYYMMDD-->\n\t<!--Sabit Tekrarlı Satış Bitiş-->\n\n\t<!--Değişken Tekrarlı Satış Başlangıç-->\n\t<input type=\"hidden\" name=\"recurringamount1\" value=\"\" />\t<!-- 1. Değişken tutar -->\n\t<input type=\"hidden\" name=\"recurringamount2\" value=\"\" />\t<!-- 2. Değişken tutar -->\n\t<!-- + istenilen taktirde ek tutarlaar recurringamount3 4 5 ... olarak eklenebilir.-->\n\t<!--Değişken Tekrarlı Satış Bitiş-->\n\n\t<!--EK Parametreler Bu Alana Eklenebilir Bitiş _____________________________ -->\n\n\t<!--Müşteri Kart Üzerindeki Adı-->\n\t<input name=\"cardholdername\" value=\"Test User\" />\n\t<!--Müşteri Kart Numarası-->\n\t<input name=\"cardnumber\" value=\"5406697543211173\" />\n\t<!--Müşteri Kartı Son Kullanma Ay-->\n\t<input name=\"cardexpiredatemonth\" value=\"03\"/>\n\t<!--Müşteri Kartı Son Kullanma Yıl-->\n\t<input name=\"cardexpiredateyear\" value=\"23\" />\n\t<!--Müşteri Kartı CVC Güvenlik Numarası-->\n\t<input name=\"cardcvv2\" value=\"465\" />\n</form>
Aşağıda yer alan html formatındaki form yapısı, Sanal POS Satış altındaki tüm 3D'li işlem tipleri için hem ortak hem de farklılaşan etiketleri içermektedir.
İşlem tipine, ilgili açıklama sayfası içerisinde, bu ortak yapı üzerinde yapılması gereken değişklikler detaylıca anlatılmaktadır.
Sanal POS Satış 3D'li Ek Alanlar Özel Alan Gönderimi İşlemine Özel Form Yapısı Düzenlemeleri
Yukarıda verilen ortak html yapısı üzerinde; aşağıdaki işlemler sağlanarak, işlem tipi için gerekli olan form yapısı elde edilebilir:
"EK Parametreler Bu Alana Eklenebilir Başlangıç" açıklaması ile başlayan ve "EK Parametreler Bu Alana Eklenebilir Bitiş" açıklaması ile biten tüm kod bloğu silinmelidir.
Kod bloğu içerisinde aşağıdaki şekilde belirtilen satırda "sales" olarak ifade edilen işlem tipi, Peşin işlem tipini belirtir. Bu alan oldugu gibi korunmalıdır:
<input type=\"hidden\" name=\"txntype\" id=\"txntype\" value=\"sales\" />
Bu işlem tipine özel olarak; aşağıda belirtilen kod bloğu form yapısı içerisine eklenmelidir:
<!--Özel Bilgi Alanı-->\n<!--Özel Bilgi Toplam Adedi-->\n<input type=\"hidden\" name=\"ordercommentcount\" value=\"1\" />\n<!--Özel Bilgi No-->\n<input type=\"hidden\" name=\"ordercommentnumber1\" value=\"1\" />\n<!--Özel Bilgi Açıklama Metni-->\n<input type=\"hidden\" name=\"ordercommenttext1\" value=\"Bu alana kullanılmak istenilen bilgi yazılmalı\" />
İşlemin başarılı olması durumunda, üye iş yeri tarafından aşağıdaki kod bloğu içerisinde başarılı işlem dönüşünün parametrelerinin karşılanacağı sayfa url'i yazılmadıır:
<!--Başarılı İşlem Dönüş Bağlantısı-->\n<input type=\"hidden\" name=\"successurl\" id=\"successurl\" value=\"oospayment/result\" />
İşlemin başrısız olması durumunda, üye iş yeri tarafından aşağıdaki kod bloğu içerisinde başarılı işlem dönüşünün parametrelerinin karşılanacağı sayfa url'i yazılmadıır:
<!--Başarısız İşlem Dönüş Bağlantısı-->\n<input type=\"hidden\" name=\"errorurl\" id=\"errorurl\" value=\"oospayment/result\" />
Yukarıda belirtilen işlem tipine özel ekleme ve çıkarma işlemlerinden sonra form bloğu hazır hale gelir ve ilgili html sayfası içerisine yerleştirilir.
Formun ziyaretçiler tarafından doldurulması ve gönderilmesi sonrasında, işlem Garanti BBVA Satış sayfası içerisinde devam eder.
Satış Sayfası İşlem Cevabı
Satış sayfasında işlem tamamlandıktan sonra, sistem tarafından önceki adımlarda belirlenen adrese bir form post edilecektir (Başarılı işlem url veya başarısız işlem url)
İlgili adreste yer alan sayfa içerisinde, sistemden gelen bu form verilerinin; burada anlatıldığı şekilde parse edilmesi gerekmektkedir.
Aşağıdaki tabloda; sistemden gelen verilerin açıklamaları yer almaktadır. Parse işleminden sonra elde edilen verileri bu tabloya göre yorumlanmalıdır:
| Alan Adı | Açıklaması |
|---|---|
| mdstatus | 3D cevabı numeric olarak verildiği alan |
| mderrormessage | 3D cevabı işlem durumunun metin olarak açıklaması |
| errmsg | 3D cevabı hatalı işlem durumlarında hata mesajı |
| clientid | Üye işyerine ait terminal id bilgisi |
| oid | İşlem yapılırken gönderilen sipariş numarası |
| response | İşlemin başarılı olup olmadığını gösteren alan |
| procreturncode | Provizyon cevabı |
| successurl | Başarılı işlem durumunda dönecek url bilgisi |
| txninstallmentcount | İşlem yapılırken gönderilen taksit sayısı |
| refreshtime | İşlem yapılırken gönderilen yenileme süresi |
| orderid | İşlem yapılırken gönderilen sipariş numarası |
| cardholdername | İşlem yapılırken gönderilen müşteri adı |
| txntype | İşlem yapılırken belirtilen işlem tipi |
| terminalmerchantid | İşlem yapılırken üye işyeri numarası |
| txnamount | İşlem yapılırken gönderilen toplam tutar bilgisi |
| txntimestamp | İşlem zamanı |
| terminaluserid | Üye işyeri kullanıcı adı |
| mode | İşlem yapılan ortam bilgisi |
| txncurrencycode | İşlem yapılırken belirtilen para birimi |
| secure3dhash | İşlem yapılırken hesaplanan hash bilgisi |
| apiversion | İşlem yapılırken gönderilen API versiyon bilgisi |
| companyname | Üye işyeri adı |
| errorurl | İşlem yapılırken gönderilen hatalı işlemlerin dönüleceği url bilgisi |
| secure3dsecuritylevel | İşlem yapılırken belirtilen 3d model bilgisi |
| customeremailaddress | İşlem yapılırken gönderilen müşteri eposta bilgisi |
| customeripaddress | İşlem yapılırken gönderilen müşteri IP adres bilgisi |
| terminalid | Terminal numarası |
| terminalprovuserid | İşlem yapılırken gönderilen provizyon kullanıcı bilgisi |
| lang | İşlem yapılırken gönderilen servis cevap dil tercih bilgisi |
| hash | İşlem sonrasında oluşan hash verisi |
| hashparams | İşlem sonrasında kullanılacak hash formül bilgisi |
| hashparamsval | İşlem sonrasında kullanılacak hash detayları |
Önemli Hatırlatma : Kurulum sonrasında yapılacak işlemler dönüşlerindeki provizyon sonuçlarını kontrol etmeden önce;
- Dönen verinin bankadan gelip gelmediğinden emin olmanız gerekmektedir. Bunu yapmak için birkaç metod bulunmaktadır. Dönen değerlerdeki hash değerinin, dönen değerlerden oluşturarak oluşturulacak hash değeri ile aynı olması, (hashparams değerini dönen değerlerden hesaplanmalı hashparamsval kullanılmamalıdır.)
- Her işlem sonrasında orderinq işlem tipini kullanarak xml ile sorgulama yaparak sorgulama sonucuna göre işleme devam edilmesi,
- Her siparişin kargolanmadan önce sanal pos yönetim ekranlarından kontrol edilmesi,
- Siteden sanal posa post edilen tutar değeri müşterinin site üzerinde gördüğü yada bir önceki sayfadaki sepet tutar yerine veri tabanından çekilecek tutar kullanılmalı,
- İşlem sonucunda dönen tutar ile orijinal işlem tutarını kontrol edebilir,
- Şifreli cevap yapısına geçebilir, Bu yapıda tutar şifreli alanlar içerisinde geleceği için tutarın değiştirilmesi söz konusu olmaz. Kullanıcı cevapta dönen işlem tutarı ile işlemdeki tutarı kontrol ederek işlemde oynama olup olmadığını bu şekilde daha güvenli olarak yakalar.
- Firma satış sonrasında orderinq yada orderhisinq fonksiyonlarını kullanarak sorgulama sonrasında işlem durumunu kontrol edip, gelen tutarla, sepet tutarını karşılaştırabilir.
Dönüş sadece 00 için kontrol yapılmalıdır. Diğer durumlar için gerek olmadığı gibi hesaplama yapılamaz.
string responseHash = Request.Form.Get(\"hash\");\nchar[] separator = new char[] { ':' };\n\n// Ayıraç için kullanıcak hashparams\nstring responseHashparams = Request.Form.Get(\"hashparams\");\n\n//Bu alanda dönen parametrelerin isimlerine göre tek tek değerleri alınır.\nstring[] paramList = responseHashparams.Split(separator);\n\nforeach (string param in paramList)\n{\n digestData += Request.Form.Get(param) == null ? \"\" : Request.Form.Get(param);\n}\n\n//Sonuna store key eklenir\ndigestData += strStoreKey;\n\n// Aşağıdaki gibi şifreleme uygulanır.\nvar sha = new System.Security.Cryptography.SHA512CryptoServiceProvider();\nbyte[] hashbytes = System.Text.Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(digestData);\nbyte[] inputbytes = sha.ComputeHash(hashbytes);\nString hashCalculated = Convert.ToBase64String(inputbytes);\n\nif (responseHash.Equals(hashCalculated))\n{\n Response.Write(\"!!!!!MESAJ BANKADAN GELİYOR!!!!!\");\n isValidHash = true;\n // Evet bankadan geliyor\n}
- Beklenen sipariş nosu mu ?
- Request.Form.Get("procreturncode") 00 mı ?
- Request.Form.Get("hashparams"); null veya "" olmamalı
Yukarıdaki kontroller sonrasında eğer sonuç başarılıysa işlem onaylanmalıdır.
'hashparams' => 'clientid:oid:authcode:procreturncode:response:mdstatus:cavv:eci:md:rnd:',
Hashparams yukarıdaki şekilde sırası ile oluşturulmaktadır. Daha sonrasında sonuna 3d Key eklenerek sha512 ile şifrelenmektedir. Sonuç ile Request.Form.Get("hash"); aynı olması durumunda sonuç başarılıdır. Aksi taktirde işlem kontrol edilmelidir.
Kod Örnekleri
Aşağıda bu işlem tipinin de yer aldığı, farklı yazılım dilleri ile yazılmış özel kod örneklerine ait github repo linkleri verilmiştir. Tercih ettiğiniz programlama diline ait link üzerinden ön tanımlı değerlerle yazılmış olan kodları inceleyebilirsiniz.
- C# Kod Örnekleri için tıklayınız.
- VB.Net Kod Örnekleri için tıklayınız.
- Java Kod Örnekleri için tıklayınız.
- PHP Kod Örnekleri için tıklayınız.
Hata Kodları
Hata kodlarına bu sayfadan ulaşabilirsiniz.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsiniz.
