-
Security Platform
Security Platform
Cirom Secured General Concept
This document details the requirements for merchants that will integrate Garanti BBVA Fraud Module.
In addition to the information in the document, information such as endpoints used, request/response field names and types, error codes can be accessed via the link below and a sample post request can be sent.
Test Environment
Test environment address: atalantegwtest.garanti.com.tr
Swagger: https://atalantegwtest.garanti.com.tr/swagger-ui.html
| Title | Value |
|---|---|
| MerchantId | 7000679 |
| Password | 123qweASD/ |
| MerchantId | 3424113 |
| Password | 123qweASD/ |
Production Environment
Prod media address: https://atalantegw.garanti.com.tr
Garanti Bank Security Platform Technical Integration Document
The fully authorized user determines the password to be used when creating the encoded hash value during messaging between the workplace system and Atalante services by entering the relevant values in the "Password" input fields on the screen.
This value is kept in the system by default when the fully authorized user first accesses the Fraud Module.
The user enters the password he/she has set in the "Password", "Password Repeat" fields and writes the values in the captcha on the screen in the relevant field and presses the SAVE button and the password is reset.
Request Header Tag and Content
In Garanti BBVA Fraud Module, request messages are sent with the "requestHeader" header tag and its content. The fields that must be sent under the "requestHeader" tag and their contents are detailed in the table below.
| Data Field | Necessity | Description | Length/Format/Values |
|---|---|---|---|
| gvpsMerchantNum | Mandatory | This is the field where the associated Garanti BBVA workplace number is sent. | The workplace number value allocated to the workplace by Garanti BBVA is sent in this field. |
| hashData | Mandatory | It will be the information to be used to ensure the security of the sent request. With this information, sending transactions to the system other than the permitted workplace will be prevented. | The method of calculating the "hashData" value is detailed. |
| orderId | Mandatory | This is the field where the order number of the transaction to be sent is sent. | |
| transactionType | Mandatory | The transaction type information that the workplace will perform the provision must be sent in this field. Table 6 shows the values that the field can take. | |
| uniqueId | Mandatory | It is the Unique ID value returned to the workplace during the device ID determination process. | The unique value obtained when the PageLoad process is finished is sent in this field. 24 characters long, alphanumeric. |
Sample request header message fragment is given below.
\"requestHeader\": { \n \"gvpsMerchantNum\": 100018660,\n \"hashData\": \"52946e0693e3ae2679194a43bbf6baf220369e33\", \n \"orderId\": \"asdqwer1234567\",\n \"transactionType\": \"sales\",\n \"uniqueId\": \"Wjk5NDVGRTE2Q0ZGNDVENTgw\"\n}
Calculation of HashData Area
How to perform the hash calculations in the document is explained under this heading. The "hashData" value is calculated in two stages.
HashData= SHA1(MerchantNum&TransactionType&OrderID&UniqeuID&HashedPassword)
- MerchantNum: Merchant number. Regardless of how many digits the merchant number is, it will be written into the hash data as it is.
- TransactionType: Transaction type information.
- OrderId: Transaction order number information.
- UniqueId: Unique ID information returned to the workplace during the device ID determination process.
- HashedPassword: Hashed password information. Hashed password information is calculated as follows.
HashedPassword: UPPERCASE (SHA1 (Password&MerchantNum))
- Password: Merchant password information.
- MerchantNum: Merchant number. Merchant number should be included in the calculation as 8 digits.
For workplace numbers less than 8 characters 0 must be added to the beginning of the number to complete 8 digits.
Example 1;
Workplace number: 123456
Workplace number to be added to the calculation: 00123456
Example 2;
Workplace number: 1234567
Workplace number to be added to the calculation: 01234567
For 8 character workplace numbers will be written as it is without any addition at the beginning of the workplace number.
Example;
Workplace number: 12345678
Workplace number to be added to the calculation: 12345678
For workplace numbers with more than 8 characters The workplace number will be 8 digits and 1 or more characters will be trimmed from the right of the workplace number and included in the hash calculation.
Example 1;
Workplace number 123456780
Workplace number to be added to the calculation: 12345678
Example 2;
Workplace number: 1234567801
Workplace number to be added to the calculation: 12345678
For MerchantNum and Password values, you can get information from our E-Commerce Support ETicaretDestek@garantibbva.com.tr team.
Example Hashed Password Calculation
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
Score Enquiry Process
Merchants using the Garanti BBVA Fraud Module can ensure that a score is generated for each transaction by sending the fields shared below in the score query request.
The message structure to be created by the merchant must be in JSON format.
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
The sample message structure of the score enquiry request is given below.
Service Request Example
{\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}
Service Request Response Example
{\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}
Obtaining Product Information
In the score query request, information about the product categories and features purchased under the "productDetails " tag should be shared.
The fields to be sent in the score query request are as follows..
| Data Field | Necessity | Description | Length/Format/Values |
|---|---|---|---|
| itemGift1 | Optional | Information about whether gift wrapping is used in the product should be sent in this field. | If gift wrapping option is selected for the product, "Y" value should be sent in this field. If a value other than "Y" is received, it will be evaluated as "N" (no gift wrapping). |
| itemGift2 | Optional | The information that the campaign or coupon is used must be sent with Y value in this field. | If a value other than "Y" is received, it will be evaluated as "N" (no coupon campaign usage). |
| itemInspInd | Optional | The information that the ordered product category was examined in the previous session should be sent in this field. | The information that the ordered product category was examined in the previous session must be sent with the value "Y" in this field. If a value other than Y is received, it will be evaluated as N (not examined). |
| numberOfItemsPurchased | Optional | The number of products in the basket must be sent in this field. | Format: Numeric |
| numberOfDistinctItemsPurchas ed | Optional | The number of different products in the basket must be sent in this field. | Format: Numeric |
| numberOfPurchasePerDay | Optional | Format: Numeric | |
| numberOfItemsPurchasedPerD ay | Optional | Format: Numeric | |
| numberOfRiskyProductsPurcha sed | Optional | The number of risky products in the basket should be in this field. The workplace should fill in this field for the products that they think contain risk for themselves. | Format: Numeric |
| productList | Optional | This is the field where the product list is sent. | Json data type : Object Multiple ArrayExamine Table 7 ProductList table for the data elements it contains. |
Product List Detail
| Data Field | Necessity | Description | Length/Format/Values |
|---|---|---|---|
| amount | Optional | This is the field where the product amount information is sent. | This field must be sent with the last 2 digits in cents without any penny distinction. Example: 1 TL is sent as "amount" = "100". |
| productCategory | Optional | This is the field where product category information is sent. | Table 4 The codes corresponding to the product categories from the product category codes table should be sent |
| productNames | Optional | This is the field where the product name information is sent. | Format: Text |
| quantity | Optional | This is the field where product quantity information is sent. | Format: Numeric |
| value1 | |||
| value2 | |||
| value3 |
A sample message thread is given below.
\"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"//card number "I"//ip address "D"//device "E"//email "P"//phone number "ID"//national number "NS"//name and surname |
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.
