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 Inquiry

It is the service used when it is desired to query the tokens generated as a result of a token acquisition request.

Parameters to be sent to Service

The parameters that must be sent in addition to the Request Header tag in the token query service are as follows:

Parameters Returned from Service

The parameters returned from the token query service in addition to the response header field are as follows:

Sample Request Message

The token query sample request and response is as follows.

Sample Reply Message

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.