-
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 Workplace Result Process
After the response returned to the workplace in the score request, the workplace must share the latest status information with the fraud module.
If the transaction is continued for authorisation, the authorisation information must also be in the transaction feedback.
The message structure to be created by the workplace is prepared in JSON message structure format and requests are sent to https://atalantegwtest.garanti.com.tr/scoreResult URL.
The score query request sample message structure is given below.
TEST URL: https://atalantegwtest.garanti.com.tr/scoreResult \nPROD : https://atalantegw.garanti.com.tr/scoreResult\n\nHeaders:\ncontent-type: application/json;charset=UTF-8 \nversion: v1
{\n \"requestHeader\": {\n \"uniqueId\": \"N0Q0NTI0NjRCQTY1NDBCNThB\",\n \"relatedGVPSMerhcant\": 123456,\n \"hashData\": \"B29C2D40A38318D36F3227E9D2C986FC4C5A89C3\",\n \"orderId\": \"6E6FA33577034E858A56691B5BC55602\",\n \"transactionType\": \"sales\"\n },\n \"merchantDecision\": \"01\",\n \"responseCode\": \"00\",\n \"reasonCode\": \"00\"\n}
The information of the content to be sent under the "requestHeader" tag is detailed under Request Header Tag and Content. The request message will be made with the unique id number returned in the scoring request.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| merchantDecision | Provision decision of the workplace must be sent in this field. | A 2 byte data will come in this field.01- not continued because it is considered risky02 - Provision continued |
| responseCode | The response code returned from the provision must be sent in this field. | |
| reasonCode | The detail response code returned from the provision must be sent in this field. |
Score Enquiry Workplace Result Answer
In the reply message returned to the workplace, there is information about whether the transaction has successfully reached the system.
| 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 OK01 Authentication Error 03 Scoring module error (if we had trouble transmitting the transaction to the scoring module)04 Input DataError08 Already sent score result information09 Related transaction not found 99 General Error |
| responseMsg | This is the field where the answer text of the error code will be returned in erroneous returns. | 00 OK 01 Authentication Error 03 Scoring module error (if we had trouble transmitting the transaction to the scoring module)04 Input Data Error08 Already sent score result information09 Related transaction could not be found99 General Error |
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.
