-
Card Storage
Card Storage
Card Storage General Concept
By using token retrieval services, merchants obtain a unique token by ensuring that the customer card information they send in the transaction is securely encrypted on Garanti Bank servers without creating a payment. During the service call, validation checks are performed for the card from which the token is obtained. If the card is eligible for authorization, the token information generated as a result of the transaction is returned to the merchant in the response message.
For token purchase transactions sent with bank cards other than Garanti Bank cards, a sale transaction of 0.11 TL is made by the system for each token purchase transaction for card validation. If the sale transaction is successful, a token value is generated for the card and the sale transaction of 0.11 TL is automatically canceled. This transaction is not displayed on the cardholder's e-statement.
Merchants should store the token information returned in the service response by associating it with customer data (e.g. registration number, customer number, etc.) for later use in payment transactions.
The token information generated on Garanti Bank servers instead of the card information or customer information sent in the transaction is stored in a form associated with the merchant. The management and use of tokens belongs to the merchant.
Test Environment
The TEST BASE URL to be used for testing Card Storage and Switch services is as follows:
TEST BASE URL: https://gbtaksimtunel-integration.garanti.com.tr/
Note: This TEST BASE URL represents the virtual environment offered by Garanti Bank and is intended to be used for testing purposes instead of real transactions. Transactions in this environment do not have real financial implications as in a live environment and only work through test scenarios.
The test environment allows to test the performance and reliability of the application by simulating different scenarios and error conditions. It can also be used to verify that API requests and responses are processed correctly.
During testing, it is important to understand how to react to potential error situations, how to handle errors and how to ensure that the system is working correctly. Testing is also important for security and compliance, and a successful testing phase must be achieved before going live.
It should be noted that errors in the test environment may be temporary. The development team should prefer to contact ETicaretDestek@garantibbva.com.tr support units in case possible errors recur frequently. In this way, problems will be solved more quickly and effectively, ensuring that the testing process proceeds efficiently. Successful testing contributes greatly to the safe and smooth transition of the application and systems to the live environment.
The following information can be used to send in API requests in the test environment. These values will be used in all request types:
| Title | Value |
|---|---|
| Switch ID: | CC82C381E078482AB328943FCCB7100C |
| Switch Şifresi: | 123asdASD@ |
This is the authentication information that will be used to test the Card Storage and Switch APIs. Care must be taken to use these credentials correctly in order to perform the tests successfully and get accurate results. Making sure that API requests are made with these credentials is important for the reliability and success of the tests.
Production Environment (Obtaining Merchant Credentials)
In order to send requests with real data in the production environment of the merchant, after the integration is completed in the test environment, the merchant must obtain the Switch ID value by sending the Garanti Sanalpos terminal number to ETicaretDestek@garantibbva.com.tr.
Based on the obtained Switch ID value, the hash data created for security purposes in API requests must be calculated. This hash data must also include the Switch Password of the merchant. Details about the hash calculation will be explained in the following sections.
The Switch Password of the member workplace must be created under the Password Update menu on the management screens of the member workplace. This process is performed by the member workplace admin user.
Detailed information about creating a Switch Password can be found under the "Password Update" heading. In this way, merchants can securely make API requests with real data and successfully complete the GarantiBBVA Switch integration.
API Request and Response Header Information
In all JSON API requests to the card storage and Switch system, the Request Header field must be sent completely. With these fields, the fields in the related transaction are checked and it is checked whether the data sent is valid or not. The response header field will be returned in the JSON API response information of all of the aforementioned requests. Content-Type of all JSON API requests must be application/json type. Again, the encoding of all JSON API requests must be in UTF-8 format.
Request Header tag and the parameters to be sent under it are as follows:
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| requestId | String | Yes | Max 36 Character | The unique ID value generated for each transaction. |
| swtId | String | Yes | Max 36 Character | This is the field where the switch ID value defined on behalf of the workplace or company performing the operation is sent. In tests, the swtId transmitted in the upper segment can be used. For the Prod environment, the swtId defined for the workplace should be used. |
| timestamp | String | Yes | - | Transaction time is sent in this field. |
| userId | String | Yes | Max 36 Character | This is the field where the ID value of the user who performed the transaction is sent. Any data can be sent, but it is recommended to be a workplace specific value. The purpose of this data is to distinguish which person or system is handling the request. |
| hashedData | String | Yes | - | By the workplace JSON API Request Hash Calculation Example The value generated by calculating the hash according to the criteria given under the heading is sent in this field. |
The Response Header tag and the parameters to be returned under it are as follows:
| Field | Type | Description |
|---|---|---|
| requestId | String | It is the unique ID value generated for each transaction. It will hold the same value as the field sent in the request header. |
| swtId | String | This is the field where the switch ID value defined on behalf of the workplace or company performing the transaction is sent. It will hold the same value as the field sent in the request header. |
| timestamp | Timestamp | The transaction time is sent in this field. The value here is the timestamp of the transaction in the Card Storage and Switch system. |
| userId | String | This is the field where the ID of the user who performed the transaction is sent. It will hold the same value as the field sent in the request header. |
| hashedData | String | JSON API Response Hash Calculation ExampleA hash is calculated according to the criteria given under the heading and the generated value is sent in this field. |
In all JSON API responses, in addition to the header field, a Map called errorMap is returned outside the header field, which indicates whether the fields sent in the request contain data errors.
| Field | Type | Description |
|---|---|---|
| errorMap | Map<String, String> | It tells whether the fields sent in the request contain a data error. |
Hash Calculation for Service Calls
The following describes the header tag and fields of a sample request message to be sent to the Warranty Switch APIs:
\"header\": {\n \"requestId\": \"unique_request_id\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"timestamp\": \"15032021151020\",\n \"hashedData\": \"Buraya hesaplanan hash değeri gelmelidir\"\n}
HashedData Calculation:
The "HashedData" field is used to verify the integrity of the API request for security purposes. The following steps are followed to calculate this field:
- Concatenate: Öncelikle, "requestId", "swtId", "userId" ve "timestamp" ve "swtPassword" değerleri birleştirilir.
- Hashing: Daha sonra, bu birleştirilmiş değer, SHA256 algoritması kullanılarak bir hash değerine dönüştürülür.
- Uppercase: Son olarak, elde edilen hash değeri büyük harfe çevrilir.
Sample Data and Calculation
requestId = \"unique_request_id\"\nswtId = \"CC82C381E078482AB328943FCCB7100C\"\nuserId = \"your_user_id\"\ntimestamp = \"15032021151020\"\nswtPassword = \"123asdASD@\"\n\nConcatenatedValue = \"unique_request_idCC82C381E078482AB328943FCCB7100Cyour_user_id15032021151020123asdASD@\"\nHashedData = UPPERCASE(SHA256(ConcatenatedValue))\nHashedData = \"1188B66CDFDDBAAD848CDFCC0749E1B41BC0AD8BD7F9D6004E45517400095933\"\n
Calculated Final Header Data Example
\"header\": {\n \"requestId\": \"unique_request_id\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"timestamp\": \"15032021151020\",\n \"hashedData\": \"1188B66CDFDDBAAD848CDFCC0749E1B41BC0AD8BD7F9D6004E45517400095933\"\n}
Hash Calculation for Service Responses
The sample response header information and the hash calculation method for this information to verify the hashedData parameter in the response returned in the transaction results are as follows:
Sample Response Header
\"header\": {\n \"requestId\": \"ba0e96080c7b4216847ef71197d4ad06\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1615734734018,\n \"hashedData\": \"937D994CF3CB41912FE90595FD431197DB809B9C968B4C9F652B637434BCAAA5\"\n}
HashedData Calculation:
The "timestamp" field in the Response is returned as Unix Timestamp, but this value must be used in String format for hash calculation. Therefore, the Unix Timestamp value must be converted to String format.
The following steps are followed for HashedData calculation:
- Concatenate: "requestId", "swtId", "returnCode", "reasonCode", "message" ve "timestamp.getTime()" değerleri birleştirilir. "timestamp.getTime()" ile Unix Timestamp değeri String formatına dönüştürülür.
- Hashing: Birleştirilmiş bu değer, SHA256 algoritması kullanılarak bir hash değerine dönüştürülür.
- Uppercase: Son olarak, elde edilen hash değeri büyük harfe çevrilir.
Example HashedData Calculation:
requestId = \"ba0e96080c7b4216847ef71197d4ad06\"\nswtId = \"CC82C381E078482AB328943FCCB7100C\"\nreturnCode = \"00\"\nreasonCode = \"00\"\nmessage = \"Başarılı\"\ntimestamp = 1615734734018 (Unix Timestamp değeri)\nSwitch Password = \"123asdASD@\"\n\nHashedData hesaplaması için bu değerler kullanılırsa:\n\nConcatenatedValue = \"ba0e96080c7b4216847ef71197d4ad06CC82C381E078482AB328943FCCB7100C0000Başarılı1615734734018123asdASD@\"\nHashedData = UPPERCASE(SHA256(ConcatenatedValue))\nHashedData = \"937D994CF3CB41912FE90595FD431197DB809B9C968B4C9F652B637434BCAAA5\"\n
The hashedData value is the same as the value specified in the sample response header. In this way, the correctness of the hashedData value in API responses can be verified and data integrity is ensured.
Token Retrieval via API Request
It is a service that enables token generation with the entire card number or the first 6 and last 4 digits of the card for Garanti Bank cards, the expiration date of the card and the customer number or TRKN. API URL information for the prod and test environment is as follows.
PROD Environment:\nhttps://kartsaklamabackend.garanti.com.tr/api/token/generate\n\nTEST Environment:\nhttps://gbtaksimtunel-integration.garanti.com.tr/api/token/generate
Parameters to be sent to Service
The token generate request is used for token generation with full card or token generation with the first 6 and last 4 digits of the card for Garanti Bank cards. For these two functions, distinction is provided with the value to be sent in the "registrationType" field.
If token retrieval is done with full card number, 'F' value should be sent in the "registrationType" field.
For Garanti Bank cards, if the token is received with the first 6 and last 4 digits of the card, the value 'M' must be sent in the "registrationType" field.
The parameters that must be sent in addition to the Request Header field in the token receiving service are as follows.
Card Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| cvv | String | No | 3 Character | The 3-digit number on the back of the card. |
| expireMonth | String | mandatory if registrationType = F | 2 Character | The month on the card. |
| expireYear | String | mandatory if registrationType = F | 2 Character | The year on the card. |
| first6 | String | Mandatory if registrationType = M | 6 Character | First 6 digits of the card. |
| holderName | String | No | Max Character: 50 | The name on the card. |
| last4 | String | Mandatory if registrationType = M | 4 Character | Last 4 digits of the card. |
| number | String | mandatory if registrationType = F | Min: 15 CharacterMax: 30 Character | Card number. |
Cardholder Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| customerNumber | String | Mandatory if registrationType = M | Max20 Character | Garanti Bank customer number. |
| String | No | Max128 Character | Customer e-mail address information. | |
| gsm | String | No | Max16 Character | Customer cell phone number information. |
| ip | String | No | Max20Character | Customer IP address information. It must be in IPv4 format. |
| lastName | String | No | Max50 Character | Customer last name information. |
| name | String | No | Max50 Character | Customer name information. |
| nationalNumber | String | Mandatory if registrationType = M | Max20 Character | Customer ID number. |
Extra Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| additionalData | String | No | Max 120 Character | It is used to send information such as policy number etc. to be associated with the token or to manage scenarios where different customers store the same card. If no value is sent in this field, the same token value is generated for the same card. If the token information received for the card needs to be differentiated for the policy number or a similar value, this differentiation can be provided with the additionalData field. |
| registrationType | String | Yes | 1 Character | Indicates whether the transaction will be performed with full card data or with the first 6 and last 4 digits of the Garanti card. 'F' should be sent if token retrieval will be performed with full card data. If the request will be sent with the first 6 last 4 digits, 'M' value should be sent. |
Parameters Returned from Service
The parameters returned from the token receiving service in addition to the Response Header field are as follows:
Card Information
| Field | Type | Description |
|---|---|---|
| token | String | The token ID value generated as a result of the transaction. This value should be stored by the merchant in relation to the customer to be sent in payment transactions. |
| binNumber | String | Bin number (first 6 digits) of the card used in the transaction. |
| bankId | String | ID of the bank where the card used in the transaction is registered. |
| maskedNumber | String | Masked version of the card used in the transaction. |
| bankName | String | The name of the bank where the card used in the transaction is registered. |
1. Sample Request Message
Sample JSON requests and responses for token retrieval are as follows:
{\n \"header\": {\n \"requestId\": \"36d5856c34e34799927571fe9cc18fca\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"hashedData\": \"08F68F708DF9806EFA3DDA16F4B1D0694CC6BAF5350612836C205A7DB31F0C08\",\n \"timestamp\": \"2021-03-15T21:30:07.107Z\"\n },\n \"additionalData\": \"e124f33e70464f55bf3d6211b394c286\",\n \"registrationType\": \"F\",\n \"card\": {\n \"number\": \"5549601449497017\",\n \"expireMonth\": \"02\",\n \"expireYear\": \"25\"\n }\n}
1. Sample Reply Message
{\n \"card\": {\n \"token\": \"281A91A144B344979C3C78F7439FE857\",\n \"binNumber\": \"554960\",\n \"bankId\": \"62\",\n \"maskedNumber\": \"554960******7017\",\n \"bankName\": \"T. GARANTİ BANKASI A.Ş.\"\n },\n \"header\": {\n \"requestId\": \"36d5856c34e34799927571fe9cc18fca\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1615843808569,\n \"hashedData\": \"3207E33004F5B27FD90F30B4CB473CF6553E4EEC7E600BBC7E4317536D42FD9C\"\n }\n}
2. Sample Request Message
{\n \"header\": {\n \"requestId\": \"2de17de4f1d342a39954edf1b2cb0010\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"hashedData\": \"7BACFD6F38B14D64C3C15D3674C0D48DF348EA7A125A8FB7AE66DC2B21C05D B2\",\n \"timestamp\": \"2021-03-15T21:32:34.008Z\"\n },\n \"additionalData\": \"7d4471b1887241cf8ded92edd8eb605b\",\n \"registrationType\": \"F\",\n \"cardHolder\": {\n \"gsm\": \"5555555555\",\n \"email\": \"user@mail.com\",\n \"ip\": \"192.168.1.1\"\n },\n \"card\": {\n \"number\": \"5549601449497017\",\n \"expireMonth\": \"02\",\n \"expireYear\": \"25\"\n }\n}
2. Sample Reply Message
{\n \"card\": {\n \"token\": \"228F2BF24B6F46F2B740C54529BC7B5E\",\n \"binNumber\": \"554960\",\n \"bankId\": \"62\",\n \"maskedNumber\": \"554960******7017\",\n \"bankName\": \"T. GARANTİ BANKASI A.Ş.\"\n },\n \"header\": {\n \"requestId\": \"2de17de4f1d342a39954edf1b2cb0010\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1615843955371,\n \"hashedData\": \"A9F7C5BF2D1481F6BA0466B965E6A72DA5847741049635076EBE8DE118B5AF4F\"\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 code for the relevant operation type and are written in different languages, so you can observe various approaches and practices. In this way, you can find the opportunity to work with more understandable and authentic examples of your preferred programming language.
Click for C# Code Examples.
Click for VB.Net Code Examples.
Click here for Java Code Examples.
Click here for PHP Code Examples.
Please note that these examples are written with predefined values and may require adaptation and security measures for use in real projects.
Test Cards
You can find the list of test cards on this page.
