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:

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:

The Response Header tag and the parameters to be returned under it are as follows:

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.

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:

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

Calculated Final Header Data Example

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

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:

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 Card Login Screen

If card information cannot be transmitted during the token retrieval request, a token retrieval request can be made with the card login screen. The redirectUrl information must be sent in the service request and accordingly, a URL will be sent to open the card login page in the directUrl field on the service return. By opening this URL in the browser, the card information screen will be accessed. Here, the token retrieval request can be made by filling in the required fields. API request path is the same as token generate.

Parameters to be sent to Service

The parameters that must be sent in addition to the Request Header field in the token receiving service with the Switch Payment Page are as follows:

Parameters Returned from Service

The parameters returned from the Switch Payment Page and token receiving service in addition to the response header field are as follows:

The parameters that will be returned as a result of the form to be executed with directUrl are as follows:

Sample Request Message

The sample request and response to receive tokens with the Switch payment page is as follows:

Sample Reply Message

Token Retrieval Response Hash Calculation with Card Login Screen

The value in the hashedData parameter returned in the transaction result form must be verified. The hash is calculated according to some fields in the form response. The fields included in the calculation in the form response are indicated in bold font. These fields are included in the calculation as String. The specified fields are concatenated and the concatenated String is hashed with SHA256 algorithm and converted to uppercase letters. In the Switch Password section, the password in the above segment should be used for test and the password defined by the workplace should be used for prod.

Card Login Screen and Token Retrieval

The card login screen can be accessed by the merchant by following the steps below and the token purchase process can be realized by entering the card information. The value generated by Direct URL is single-use and has a 5 minute usage period. If one of these two conditions is met, it is necessary to restart the flow.

The URL returned in the directUrl parameter in the reply message is opened in the browser.

Example: https://gbtaksimtunel- integration.garanti.com.tr/ui/card/store? h=e39decb2703b99683ec6ec8da24a1430f7c1eff32f2 e5ab27ec450827ad45a8f

On the card information entry screen, there are fields to enter Card Number and SKT information.

At the end of the transaction, the token information will be returned to the workplace as a form.

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.