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 3D Service Calls

One of the fields that must be sent when paying with 3D is hashedData. In this field, the hash value generated using certain fields in the content of the 3D request sent must be fed. In the hash value calculation, the following parameters sent in the request must be concatenated as String side by side and the password value generated for the Switch user must be put into the calculation. The final String value obtained is used for hash calculation using SHA256 algorithm. The String produced as a result of the hash is converted to uppercase letters and fed into the hashedData field. The method and example are as follows:

Sample Data and Calculation

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.

Getting Token with 3D

By sending a request with the HTML POST method via 3D streaming, token retrieval operations can be performed for all bank cards to the Switch module only through the Garanti Bank virtual platform.

In the HTML form to be prepared by the merchant, the addresses and form fields to send the POST request are as follows. Each of the fields must be sent as String.

Token Receipt/Update Request Form Fields with 3D

Receiving Token with 3D Answer Form Fields

3D Secure response message will be POSTed as HTML Form by Switch 3D Secure Gateway to the successUrl or failureUrl addresses sent by the merchant in the request message together with the data set below.

Sample Request and Response Form for Receiving Token with 3D

A sample HTML form for token retrieval with 3D streaming is given below in HTML Table format. After the fields here are filled in as desired, the 3D request hash calculation is made and set in the hashedData field, the token retrieval/token update request can be triggered with 3D by submitting the form to the test or prod url given below. POSTed data must be application/x-www- form-urlencoded type.

3D HTML Response Form Example (Token Retrieval)

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.