-
Sanal Pos
Security Platform
Cirom Güvende Genel Kavram
Bu dokümanda Garanti BBVA Fraud Modülü entegrasyonu yapacak işyerleri için gereksinimler detaylandırılmıştır.
Dokümandaki bilgilere ek olarak aşağıdaki link üzerinden de kullanılan endpointler, request/response alan isimleri ve tipleri hata kodları gibi bilgilere ulaşılabilir ve örnek post isteği gönderilebilir.
Test Ortamı
Test ortam adresi: atalantegwtest.garanti.com.tr
Swagger: https://atalantegwtest.garanti.com.tr/swagger-ui.html
| Başlık | Değer |
|---|---|
| MerchantId | 7000679 |
| Password | 123qweASD/ |
| MerchantId | 3424113 |
| Password | 123qweASD/ |
Üretim Ortamı
Prod ortam adresi: https://atalantegw.garanti.com.tr
Garanti Bankası Güvenlik Platformu Teknik Entegrasyon Dokümanı
Tam yetkili kullanıcı ekranda yer alan "Şifre" input alanlarına ilgili değerlerin giriş yapılması suretiyle işyeri sistemi ve Atalante servisleri arasındaki mesajlaşma esnasında encoded hash değeri oluşturulurken kullanılacak şifreyi belirler.
Tam yetkili kullanıcı Fraud Modülüne ilk eriştiğinde bu değer sistemde default olarak tutulmaktadır.
Kullanıcı belirlediği şifreyi "Şifre", "Şifre Tekrar" alanlarına girerek ve ekranda yer alan captchadaki değerleri ilgili alan yazarak KAYDET butonuna basar ve şifre resetlenir.
Request Header Tag'i ve İçeriği
Garanti BBVA Fraud Modülü’nde istek mesajları "requestHeader" header tag’i ve içeriği ile gönderilir. "requestHeader" tag’i altında gönderilmesi gereken alanlar ve içerikleri aşağıdaki tabloda detaylandırılmıştır.
| Veri Alanı | Zorunluluk | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|---|
| gvpsMerchantNum | Zorunlu | İlişkilendirilmiş Garanti BBVA işyeri numarasının gönderildiği alandır. | İşyerine Garanti BBVA tarafından tahsis edilen işyeri numarası değeri bu alanda gönderilir. |
| hashData | Zorunlu | Gönderilen isteğin güvenliğini sağlamak için kullanılacak bilgi olacaktır.Bu bilgi ile izin verilen işyeri dışında sisteme işlem gönderilmesi engellenecektir. | “hashData” değerinin hesaplanma yöntemi detaylandırılmıştır. |
| orderId | Zorunlu | Gönderilecek işlemin sipariş numarasının gönderildiği alandır. | |
| transactionType | Zorunlu | İşyerinin provizyon gerçekleştireceği işlem tipi bilgisi bu alanda gönderilmelidir. Tablo 6’da alanın alabileceği değerler yer almaktadır. | |
| uniqueId | Zorunlu | Cihaz ID belirme sürecinde işyerine dönülen Unique ID değeridir. | PageLoad süreci bittiğinde elde edilen tekil değer bu alanda gönderilir. 24 karakter uzunluğunda, alfanumeriktir. |
Örnek request header mesaj parçası aşağıda verilmiştir.
\"requestHeader\": { \n \"gvpsMerchantNum\": 100018660,\n \"hashData\": \"52946e0693e3ae2679194a43bbf6baf220369e33\", \n \"orderId\": \"asdqwer1234567\",\n \"transactionType\": \"sales\",\n \"uniqueId\": \"Wjk5NDVGRTE2Q0ZGNDVENTgw\"\n}
HashData Alanının Hesaplanması
Dokümanda yer alan hash hesaplamalarının nasıl yapılacağı bu başlık altında anlatılmaktadır. “hashData” değeri iki aşamalı olarak hesaplanmaktadır.
HashData= SHA1(MerchantNum&TransactionType&OrderID&UniqeuID&HashedPassword)
- MerchantNum: Üye işyeri numarasıdır. İşyeri numarasının kaç hane olduğu farketmeksizin olduğu şekilde hash data içerisine yazılacaktır.
- TransactionType: İşlem tipi bilgisidir.
- OrderId: İşlem sipariş numarası bilgisidir.
- UniqueId: Cihaz ID belirme sürecinde işyerine dönülen Unique ID bilgisidir.
- HashedPassword: Hashli şifre bilgisidir. Hashli şifre bilgisi aşağıdaki şekilde hesaplanmaktadır.
HashedPassword: UPPERCASE (SHA1 (Password&MerchantNum))
- Password: Üye işyeri şifre bilgisidir.
- MerchantNum: Üye işyeri numarasıdır. İşyeri numarasının 8 hane olarak hesaplamaya dahil edilmesi gerekmektedir.
8 karakterden az olan isyeri numaraları için numaranın başına 8 haneye tamamlayacak şekilde 0 eklenmelidir.
Örnek 1;
İşyeri numarası: 123456
Hesaplamaya eklenecek işyeri numarası: 00123456
Örnek 2;
İşyeri numarası: 1234567
Hesaplamaya eklenecek işyeri numarası: 01234567
8 karakter olan isyeri numaraları için işyeri numarasının başına ekleme yapılmadan olduğu gibi yazılacaktır.
Örnek;
İşyeri numarası: 12345678
Hesaplamaya eklenecek işyeri numarası: 12345678
8 karakterden fazla olan isyeri numaraları için işyeri numarası 8 hane olacak şekilde, işyeri numarasının sağından 1 ya da daha fazla karakter kırpılarak hash hesabına dahil edilecektir.
Örnek 1;
İşyeri numarası: 123456780
Hesaplamaya eklenecek işyeri numarası: 12345678
Örnek 2;
İşyeri numarası: 1234567801
Hesaplamaya eklenecek işyeri numarası: 12345678
MerchantNum ve Password değerleri için E-Ticaret Destek ETicaretDestek@garantibbva.com.tr ekibimizden bilgi alabilirsiniz.
Örnek Hashed Password Hesaplamasi
Password: password1@\n\nMerchantNum: 100018660\nHashedPassword: UPPERCASE (SHA1 (Password&MerchantNum)) Hashed Password: UPPERCASE (SHA1 (password1@10001866))=\nE12B51570844121AD09279F18E3D76EEC04190A4\n\nMerchantNum: 100018660 TransactionType: sales OrderId: 53451232223\nUniqueId: gpIJ0Oj8UEyUZjywrqt0JA==\n\nHashedPassword: E12B51570844121AD09279F18E3D76EEC04190A4\n\nHashData= SHA1(MerchantNum&TransactionType&OrderID&UniqeuID&HashedPassword)\n\nHashData= SHA1(100018660sales53451232223gpIJ0Oj8UEyUZjywrqt0JA== E12B51570844121AD09279F18E3D76EEC04190A4)=\nc27da1211a3632a59bc37779824facc83a81b4f2
Skor Sorgulama İşlemi
Garanti BBVA Fraud Modülü’nü kullanan işyerleri, skor sorgulama isteğinde aşağıda paylaşılan alanları göndererek her bir işlem için skor üretilmesini sağlayabilir.
İşyeri tarafından oluşturulacak mesaj yapısı JSON formatında olmalıdır.
TEST Ortamı URL: https://atalantegwtest.garanti.com.tr/scoreInquiry\nPROD Ortamı URL: https://atalantegw.garanti.com.tr/scoreInquiry\n\nHeaders:\ncontent-type: application/json;charset=UTF-8 \nversion: v1
Skor sorgulama isteği örnek mesaj yapısı aşağıda belirtilmiştir.
Servis İstek Örneği
{\n \"merchantAttributes\": {\n \"billingDetails\": {\n \"address\": \"Evren Mahallesi, Koçman Cd. No:34, 34212 Bağcılar/İstanbul\",\n \"city\": \"İstanbul\",\n \"country\": \"Türkiye\",\n \"district\": \"Evren Mahallesi\",\n \"latitude\": 0,\n \"longitude\": 0,\n \"zipCode\": \"34212\"\n },\n \"customerDetails\": {\n \"accountCreateDate\": \"19.02.1980\",\n \"customerId\": \"213213\",\n \"dateOfBirth\": \"10.03.1992\",\n \"email\": \"musteri@gmail.com\",\n \"firmScore\": 50,\n \"isCardRegistered\": \"N\",\n \"nameSurname\": \"Ahmet Ata\",\n \"numberOfSavedCards\": 3,\n \"phoneNumber\": \"+905068833272\",\n \"tckn\": \"45889759656\"\n },\n \"loginDetails\": {\n \"avgNumberOfLoginPerDay\": \"1.6\",\n \"isLoggedIn\": \"Y\",\n \"sessionTime1\": \"436543545765436\",\n \"sessionTime2\": \"436543545765436\",\n \"sessionTime3\": \"436543545765436\"\n },\n \"productDetails\": {\n \"itemGift1\": \"N\",\n \"itemGift2\": \"N\",\n \"itemInspInd\": \"N\",\n \"numberOfDistinctItemsPurchased\": 2,\n \"numberOfItemsPurchased\": 3,\n \"numberOfItemsPurchasedPerDay\": 0.8,\n \"numberOfPurchasePerDay\": 0.4,\n \"numberOfRiskyProductsPurchased\": 2,\n \"productList\": [\n {\n \"amount\": 0,\n \"productCategory\": \"string\",\n \"productNames\": \"iphone,tv\",\n \"quantity\": 0,\n \"value1\": \"istanbul\",\n \"value2\": \"amsterdam\",\n \"value3\": \"business\"\n }\n ]\n },\n \"sectorCode\": \"02\",\n \"sellerDetails\": {\n \"seller\": \"X Mağazası\",\n \"sellerScore\": 94\n },\n \"shippingDetails\": {\n \"address\": \"Evren Mahallesi, Koçman Cd. No:34, 34212 Bağcılar/İstanbul\",\n \"addressCreateDate\": \"29.01.2017\",\n \"addressType\": \"E\",\n \"city\": \"İstanbul\",\n \"country\": \"Türkiye\",\n \"district\": \"006\",\n \"latitude\": 0,\n \"longitude\": 0,\n \"shippingFirm\": \"001\",\n \"urgentDeliveryRequestInd\": \"N\",\n \"zipCode\": \"34212\"\n },\n \"transactionDetails\": {\n \"bkmUniqueId\": \"\",\n \"cardExpireDate\": \"0525\",\n \"cardNumber\": \"5549601678942014\",\n \"cardholderName\": \"Ahmet Ata\",\n \"currencyCode\": 949,\n \"firmBaseRewardAmount\": 0,\n \"hashedCardNumber\": \"\",\n \"installmentCount\": 0,\n \"isLoyaltyCardUsed\": \"N\",\n \"merchantNum\": \"100018660\",\n \"motoIndicator\": \"N\",\n \"numberOfDistAccountSavedThisCard\": 2,\n \"rewardAmount\": 0,\n \"terminalNum\": \"1234567\",\n \"transactionAmount\": 0,\n \"transactionSubType\": \"\"\n }\n },\n \"requestHeader\": {\n \"gvpsMerchantNum\": 100018660,\n \"hashData\": \"52946e0693e3ae2679194a43bbf6baf220369e33\",\n \"orderId\": \"asdqwer1234567\",\n \"transactionType\": \"sales\",\n \"uniqueId\": \"Wjk5NDVGRTE2Q0ZGNDVENTgw\"\n }\n}
Servis İstek Cevabı Örneği
{\n \"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\",\n \"errorContext\": null\n },\n \"riskScore\": 4821,\n \"riskScoreCutoff\": \"HR\",\n \"isInBlacklist\": \"N\",\n \"tdsInd\": \"0\",\n \"ruleEngineResults\": {\n \"actionCode\": \"00\",\n \"catched\": false\n }\n}
Ürün Bilgilerinin Alınması
Skor sorgulama isteği içerisinde "productDetails " tagı altında satın alınan ürün kategorileri ve özellikleri ile ilgili bilgi paylaşımı sağlanmalıdır.
Skor sorgulama isteği içerisinde gönderilecek alanlar aşağıdaki şekildedir.
| Veri Alanı | Zorunluluk | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|---|
| itemGift1 | Opsiyonel | Ürün içinde hediye paketi kullanılmış mı bilgisi bu alanda gönderilmelidir. | Ürün için hediye paketi seçeneği işaretlenmiş ise bu alanda “Y” değeri yollanmalıdır. “Y” dışında bir değer gelirse “N” (hediye paketi yok)olarak değerlendirilecektir. |
| itemGift2 | Opsiyonel | Kampanya ya da kupon kullanıldığının bilgisi bu alanda Y değeri ile yollanmalıdır. | “Y” dışında bir değer gelirse “N” (kupon kampanya kullanımı yok) olarak değerlendirilecektir. |
| itemInspInd | Opsiyonel | Sipariş verilen ürün kategorisi bir önceki oturumda incelendi bilgisi bu alanda gönderilmelidir. | Sipariş verilen ürün kategorisibir önceki oturumda incelendi bilgisi bu alanda “Y” değeri ile yollanmalıdır. Y dışında bir değer gelirse N ( incelenmedi)olarak değerlendirilecektir. |
| numberOfItemsPurchased | Opsiyonel | Sepetteki ürün sayısı bilgisi bu alanda gönderilmelidir. | Format: Numeric |
| numberOfDistinctItemsPurchas ed | Opsiyonel | Sepetteki farklı ürün sayısı bilgisi bu alnda gönderilmelidir. | Format: Numeric |
| numberOfPurchasePerDay | Opsiyonel | Format: Numeric | |
| numberOfItemsPurchasedPerD ay | Opsiyonel | Format: Numeric | |
| numberOfRiskyProductsPurcha sed | Opsiyonel | Sepetteki riskli ürün sayısı bu alanda yer almalıdır. İşyeri kendisi açısından risk içerdiğini düşündüğü ürünler için bu alanı doldurmalıdır. | Format: Numeric |
| productList | Opsiyonel | Ürün listesinin gönderildiği alandır. | Json data type : Object Multiple Arrayİçerdiği veri elemanları için Tablo 7 ProductList tablosunu inceleyiniz. |
Product List Detayı
| Veri Alanı | Zorunluluk | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|---|
| amount | Opsiyonel | Ürün tutar bilgisinin gönderildiği alandır. | Bu alanının kuruş ayrımı olmadan son 2 hanesi kuruş olacak şekilde gönderilmesi gerekmektedir. Örnek: 1 TL “amount” = “100” şeklinde gönderilir. |
| productCategory | Opsiyonel | Ürün kategori bilgisinin gönderildiği alandır. | Tablo 4 Ürün kategori kodları tablosundan ürün kategorilerine karşılık gelen kodların gönderilmesi gerekmektedir. |
| productNames | Opsiyonel | Ürün adı bilgisinin gönderildiği alandır. | Format: Text |
| quantity | Opsiyonel | Ürün adet bilgisinin gönderildiği alandır. | Format: Numeric |
| value1 | |||
| value2 | |||
| value3 |
Örnek mesaj parçacığı aşağıda verilmiştir.
\"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\",\n \"errorContext\": null\n },\n \"riskScore\": 4821,\n \"riskScoreCutoff\": \"HR\",\n \"isInBlacklist\": \"N\",\n \"tdsInd\": \"0\",\n \"ruleEngineResults\": {\n \"actionCode\": \"00\",\n \"catched\": false\n }
Score Enquiry Interpretation of the Response Returned to the Workplace
As a result of the scoring request, a reply containing the following data will be sent to the workplace.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| errorType | This is the field where error type information is transmitted. | |
| returnCode | This is the field where the result code of the request response will be returned. | “00” – Success“99” – General Error“01” – Authentication Error “04” – Input Data Error |
| responseMsg | This is the field where the answer text of the error code will be returned in erroneous returns. | “00” – Success“99” – General Error“01” – Authentication Error “04” – Input Data Error |
| riskScore | The value of the generated risk score will be in this field. | It will return a value between 0 - 10000. |
| riskScoreCutoff | The risk level of the risk score will be communicated to the workplace in this field. | HR - High Risk MR - Medium Risk LR - Low Risk |
| isInBlacklist | The information that the transaction is risked due to blacklist will be sent to the workplace in this field. | If it is risked due to blacklist, "Y" value will be found in this field. Otherwise, "N" value will be returned in this field. |
| tdsInd | It is the field that returns information about the E-Commerce permission and limit adequacy status of the card being processed. The information returned in this field can be interpreted and it can be decided whether the transaction will be made in 3DS or not.Limit increase for cards with insufficient limit and opening the permission for cards with closed E-Commerce permission can be done at once through the payment verification transaction via 3DS flow. For this reason, in cases where the tdsInd field returns 1, the merchant can direct the transaction to the 3DS flow and the transaction can be realised. | 0 Limit is sufficient, E-Commerce permission is open1 At least one of the following conditions: Limit is insufficient or E-Commerce permission is closed |
An example of a successful score query answer is given below.
\"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\"\n},\n\"riskScore\": 667,\n\"riskScoreCutoff\": \"HR\",\n\"isInBlacklist\": \"N\",\n\"tdsInd\": \"1\",\n\"ruleEngineResults\": {\n \"actionCode\": \"00\",\n \"catched\": false\n}
If the transaction is in the Blacklist, then the transaction will be forwarded as risky without any scoring for the transaction.
If the transaction is in the blacklist, no scoring is performed for the transaction and no score is returned to the workplace. A reply containing the following data will be sent to the workplace for the blacklisted transaction.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| isInBlacklist | The information whether the transaction is blacklisted or not is transmitted to the workplace in this field. | "Y" - the process is blacklisted."N" - the process is not blacklisted. |
| blacklistType | If the transaction is stuck in the blacklist, the information about the type of blacklist is transmitted to the workplace in this field. | "C"//kart numarası "I"//ip adresi "D"//cihazid "E"//e-posta "P" //telefon numarası "ID" //ulusal numara "NS" //ad soyad |
An example of the score query answer stuck in Blacklist is given below.
{\n \"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\"\n },\n \"isInBlacklist\": \"Y\",\n \"blacklistType\": \"C\"\n}
If the transaction is stuck in the rule defined by the workplace, a response message will be returned under the "ruleEngineResults" tag containing the details of the relevant rule and the following data.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| catchedRuleMasterId | The rule id information defined by the workplace. | Format : String |
| actionCode | It is the action code defined by the workplace after the transaction is caught by the rule and requested to be taken for the related transaction. | "00";//clear transaction "01";//block transaction "02"; //generate warning |
| additionalActionCode | If action code = 02 is selected, these are additional action codes defined by the workplace. | "01";//3D secure mandatory "02"; //Encrypted transaction mandatory "03"; //Continue with pre-authorisation "04"; //Verify transaction |
| catched | The information whether the transaction is caught by the rule is transmitted in this field. | true - The transaction was caught by the rule false - The transaction was not caught by the rule |
{\n \"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\"\n },\n \"riskScore\": 6422,\n \"isInBlacklist\": \"N\",\n \"ruleEngineResults\": {\n \"catchedRuleMasterId\": \"6F5491A8B4574D919101436B3365DED4\",\n \"actionCode\": \"02\",\n \"additionalActionCode\": \"02\",\n \"catched\": true\n }\n}
Code Examples
Below are links to custom code examples written in various programming languages. You can examine the codes written with predetermined values in detail through the link of your preferred programming language.
These examples contain the codes containing the relevant operation type and since they are written in different languages, you can also observe various approaches and practices. In this way, you can find the opportunity to work with better understandable and original examples of your preferred programming language.
Click for C# Code Examples.
Click for VB.Net Code Examples.
Click for Java Code Examples..
Click here for PHP Code Examples.
Please note that these examples are written with predefined values and you may need to take necessary adaptation and security measures for use in real projects.
Country - Province - District Codes
You can access the list of country codes from this page..
You can access the list of province codes from this page.
You can access the list of district codes from this page.
Product Category Codes
You can access the list of product category codes from this page.
Transaction Type Values
You can access the list of transaction type values from this page.
Test Cards
You can find the list of test cards on this page.
