-
Güvenlik Platformu
Güvenlik Platformu
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}
Skor Sorgulama İşyerine Dönen Cevabın Yorumlanması
Skorlama isteği sonucunda işyerine aşağıdaki dataları içeren bir cevap yollanacaktır.
| Veri Alanı | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|
| errorType | Error tipi bilgisinin iletildiği alandır. | |
| returnCode | İstek cevabına ait sonuç kodunun dönüleceği alandır. | “00” – Success“99” – General Error“01” – Authentication Error “04” – Input Data Error |
| responseMsg | Hatalı geri dönüşlerde hata koduna ait cevap metninin dönüleceği alandır. | “00” – Success“99” – General Error“01” – Authentication Error “04” – Input Data Error |
| riskScore | Üretilen risk skorunun değeri bu alanda yer alacaktır. | 0 - 10000 arasında bir değer dönecektir. |
| riskScoreCutoff | Risk skorunun risk seviyesi bu alanda işyerineİletilecektir. | HR – Yüksek Risk MR – Medium RiskLR – Low Risk |
| isInBlacklist | İşyerine işlemin blacklistten dolayı risklendirildiği bilgisi bu alanda iletilecektir. | Blacklistten dolayı risklendirildi ise bu alanda “Y” değeri bulunacaktır. Aksi durumda bu alanda “N” değeri ile dönüş sağlanacaktır. |
| tdsInd | İşlem yapılan kartın E-Ticaret izni ve limit yeterlilik durumunu bilgilerini dönen alandır. Bu alanda dönen bilgiler yorumlanarak işlemin 3DS yapılıp yapılmayacağına karar verilebilir.3DS akış üzerinden limit yetersiz kartlar için limit arttırımı, E- Ticaret izni kapalı kartlar için iznin açılması ödeme doğrulama transactionı üzerinden tekseferde yapılabilmektedir. Bu nedenle tdsInd alanı 1 döndüğü durumlarda üye işyeri işlemi 3DS akışa yönlendirerekişlemingerçekleşmesi sağlanabilir. | 0 Limit yeterli, E-Ticaret izniaçık1 Limit yetersiz ya da E-Ticaret izni kapalı durumlarından en az biri |
Başarılı skor sorgulama cevabı örneği aşağıda verilmiştir.
\"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}
İşlem Blacklist içerisinde yer alan bir işlemse bu durumda işlem için hiç skorlama yapılmadan işlem riskli olarak iletilecektir.
İşlem blackliste takıldı ise işlem için skorlama yapılmaz ve işyerine skor dönmez. Blackliste takılan işlem için işyerine aşağıdaki datayı içeren bir cevap gönderilir.
| Veri Alanı | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|
| isInBlacklist | İşlemin blackliste takılıp takılmadığı bilgisi bu alanda işyerine iletilir. | “Y” – işlem blackliste takılmıştır.“N” – işlem blackliste takılmamıştır. |
| blacklistType | İşlem blackliste takıldı ise hangi blaclist tipine takıldığı bilgisi işyerine bu alanda iletilir. | "C"//card number "I"//ip address "D"//deviceid"E"//email"P" //phone number "ID" //national number "NS" //name surname |
Blackliste takılan skor sorgulama cevabı örneği aşağıda verilmiştir.
{\n \"responseHeader\": {\n \"errorType\": \"0\",\n \"returnCode\": \"00\",\n \"responseMsg\": \"Success\"\n },\n \"isInBlacklist\": \"Y\",\n \"blacklistType\": \"C\"\n}
İşlem işyeri tarafından tanımlanan kurala takıldı ise "ruleEngineResults" tagı altında ilgili kuralın detayları ile aşağıdaki dataları içeren bir cevap mesajı dönecektir.
| Veri Alanı | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|
| catchedRuleMasterId | İşyerinin tanımladığı kural id bilgisidir. | Format : String |
| actionCode | İşlem kurala yakalandıktan sonra işyeri tarafından tanımlanan ve ilgili işlem için alınması istenen aksiyon kodudur. | "00";//işlemtemiz"01";//işlemiengelle"02"; //uyarı oluştur |
| additionalActionCode | Eğer action code = 02 seçildi ise işyeri tarafından tanımlanan ek aksiyon kodlarıdır. | "01";//3D secure zorunlu "02"; //Şifreli işlemzorunlu"03"; //Ön otorizasyon ile devam "04"; //İşlemi doğrula |
| catched | İşlemin kurala yakalanıp yakalanmadığı bilgisi bu alanda iletilir. | true – İşlem kurala yakalandıfalse – İşlem kurala yakalanmadı |
{\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}
Kod Örnekleri
Aşağıda, çeşitli yazılım dilleri kullanılarak yazılmış özel kod örneklerinin linkleri verilmiştir. Tercih ettiğiniz programlama diline ait link üzerinden, önceden belirlenmiş değerlerle yazılmış olan kodları detaylı bir şekilde inceleyebilirsiniz.
Bu örnekler, ilgili işlem tipini içeren kodları içermektedir ve farklı dillerde yazıldığı için çeşitli yaklaşımları ve pratikleri de gözlemleyebilirsiniz. Bu sayede tercih ettiğiniz programlama diline dair daha iyi anlaşılır ve özgün örneklerle çalışma imkanı bulabilirsiniz.
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.
Unutmayın ki bu örnekler ön tanımlı değerlerle yazılmıştır ve gerçek projelerde kullanımı için gerekli uyarlama ve güvenlik önlemleri almanız gerekebilir.
Ülke - İl - İlçe Kodları
Ülke kodları listesine bu sayfadan ulaşabilirsiniz.
İl kodları listesine bu sayfadan ulaşabilirsiniz.
İlçe kodları listesine bu sayfadan ulaşabilirsiniz.
Ürün Kategori Kodları
Ürün kategori kodları listesine bu sayfadan ulaşabilirsiniz.
Transaction Type Değerleri
Transaction type değerleri listesine bu sayfadan ulaşabilirsiniz.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsiniz.
