• Sanal Pos

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}

Fatura Adres Bilgilerinin Alınması

Skor sorgulama isteği içerisinde " billingDetails" tagı fatura detay bilgileri gönderilmelidir. Skor sorgulama isteği içerisinde gönderilecek alanlar aşağıdaki gibidir.

Veri Alanı Zorunluluk Açıklama Uzunluk/Format/Değerler
address Opsiyonel Fatura açık adresbilgisinin gönderildiği alandır. Format : Text
city Opsiyonel Fatura şehir bilgisinin gönderildiği alandır. Format: Tablolar başlığı altındaki Tablo 2 İl Kodları illere karşılık gelen numeric değerler gönderilmelidir.
country Opsiyonel Faturanın ülke bilgisinin gönderildiği alandır. Format: Tablolar başlığı altında yer alan Tablo 1 Ülke Kodları tablosunda belirtilen 3 haneli digit kodlar şeklindegönderilmelidir.
district Opsiyonel Fatura mahalle/sokak bilsinin gönderildiği alandır. Format: Tablolar başlığı altındaki Tablo 3 İlçe Kodları ilçelere karşılık gelen numeric değerlergönderilmelidir.
latitude Opsiyonel Enlem bilgisinin gönderildiği alandır. Format: Numeric
longitude Opsiyonel Boylam bilgisinin gönderildiği alandır. Format: Numeric
zipCode Opsiyonel Faturanıngönderileceği adresin posta kodu bilgisidir. Format: Numeric

Örnek request header mesaj parçacığı aşağıda verilmiştir.

\"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}

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.

We would love to hear from you. Do you have problems/questions about services ? Send us detailed email about it ?

Send Us a Question Send Us a Question