Card Storage and Switch Operations General Concepts

Card Storage and Switch Application offers a professional API set that enables businesses to manage online payments securely and efficiently. This special API set allows businesses to securely store customer card information, while also enabling them to initiate payment orders to multiple bank Virtualpos through this stored card data or unmasked card information.

Thanks to the Switch Management screens, businesses can manage their payment processes effectively by easily performing transactions such as cancellation, refund and pre-authorization closure. In addition, the application provides businesses with up-to-date data and information by offering the ability to instantly track transaction and order status.

Card Storage and Switch Application aims to provide businesses with a reliable payment infrastructure by focusing on the security of customer data and the smooth functioning of payment processes. With its professional and reliable service approach, it is designed to facilitate the payment acceptance processes of businesses and provide customers with an uninterrupted payment experience.

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 the live environment and only work through test scenarios.

The test environment allows testing 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 know how to react to possible error situations, how to handle errors and make sure 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.

Keep in mind that bugs in the test environment may be temporary. The development team should prefer to contact ETicaretDestek@garantibbva.com.tr support in case of recurring bugs. 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 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. The Switch Password of the merchant must also be included in this hash data account. 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 admin user of the merchant.

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.

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: First, the values "requestId", "swtId", "userId" and "timestamp" are concatenated.

• Hashing: Next, this concatenated value is converted into a hash value using the SHA256 algorithm.

• Uppercase: Finally, the resulting hash value is converted to uppercase.

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: Concatenate "requestId", "swtId", "returnCode", "reasonCode", "message" and "timestamp.getTime()". With "timestamp.getTime()" the Unix Timestamp value is converted into String format.

• Hashing: This concatenated value is converted into a hash value using the SHA256 algorithm.

• Uppercase: Finally, the resulting hash value is converted to uppercase.

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.

Payment via Switch Partner Payment Page

With Switch Common Payment page, payment flow can be started by offering "Payment by Card" and "Payment by GarantPay" options to the customer. These flows are only used for sales (auth) payment type.

In this flow, the flow is started with the parameters sent by the merchant to the service. In the parameters returned from the service, there is a link specific to the relevant request. This link is transaction-specific, expires in 1 hour and is for single use only. Switch Common Payment page is opened via the relevant link and information is entered to the customer.

Parameters to be sent to the service

The parameters that should be sent to the SOS service in addition to the Request Header tag are as follows:

Transaction Information

Acquirer Information

Invoice Information

Card Information

Cardholder Information

Installment Information

Result Information

Cargo Information

Award Information

Table-1 Installment Information List

Environment API Extensions

Json Request Example

Json Request Response Example

Common Payment Transactions Answer

The fields to be returned from the SOS service in addition to the response header tag are as follows:

Receiving Payment Information via Switch Common Payment Page

The URL returned from the SOS service opens the Switch Common Payment Page shown below. "Credit Card Payment" and "GarantiPay Payment" options are available on this screen.

Credit Card Payment Flow

When the Continue button is pressed, if the reward / installment fields have been sent in the SOS request, the following screens will open respectively. If the relevant fields have not been sent, the 3D screen will open directly.

Reward Usage Options Screen: Company/Card reward utilizations are made through this screen. All of the rewards can be used or partial rewards can be used. 

Installment Options Screen: Installment selection is made on this screen.

3D Secure Payment Screen: 3D Secure verification flow proceeds as shown in the screens below.

The verification method should be selected on the screen on the left and the "OK" button should be pressed.

When GSM is selected as the verification method, OTP SMS is sent to the relevant GSM. For the test environment, this value is fixed as 123456.

If BonusFlaş is selected as the verification method, a notification is sent to the selected device and the transaction is expected to be approved.

After selecting verification with GSM, the OTP entry screen on the right opens. The OTP value is entered in the relevant field and the OK button is pressed and the 3D Secure flow is terminated. If BonusFlaş is selected, the transaction is confirmed via the notification received on the device.

Transaction Result Screen: Transaction result information is displayed including transaction code and authorization code information..

Service Answers ErrorMap Content

In cases where the fields sent in API requests do not comply with the Card Storage and Switch system, the API will return a Map<String, String> named "errorMap" in addition to the "header" section in the response. This "errorMap" will contain information about which data is corrupted and why the data is corrupted. In this way, the relevant fields need to be edited and resubmitted.

The sample request response with ErrorMap is as follows:

vposOrderId Field in Service Responses

• Smart Switch system is integrated with more than one bank and the data format of the orderid fields of these banks may be different from each other. In order to prevent primary transactions from receiving an error due to the orderid field, a new orderid specific to the virtualpos where the Switch will route the transaction can be generated. Switch's decision whether to generate a new orderid or not can be managed with the generateOrderId parameter to be sent by the workplace.

• vposOrderId is the orderId value generated by the Switch and transmitted to the virtualpos if generateOrderId is sent as "Y" or empty in the request message or if this field is not sent at all.

• If the generateOrderId field is sent as "N", the Switch will not generate a new vposOrderId according to the format of the virtual platform to which the transaction will be routed. Since the orderid transmitted by the workplace will be forwarded to the destination virtualpos in the transaction, if the orderid is not in the format expected by the virtualpos, the virtualpos may error the transaction request due to the related field.

• If generateOrderId field "N" is sent but orderid value is not transmitted, Switch generates an orderid but this id is not created according to the format of the destination pos.

• If the orderId field is full in transaction requests where the generateOrderId field is sent "Y", sent empty or this field is not sent at all, this value continues to return in the orderId field in the response message. However, the transaction must be displayed with the vposOrderId value from the bank screens. Both orderId values will be displayed on the Switch screens; on these screens, the vposOrderId value is displayed under the Bank Order Number, and on the Transaction Detail screen, it is displayed in the ORDER_ID field under the Bank Provision Detail. If the orderId field is empty in transaction requests where the generateOrderId field is sent "Y", sent empty or this field is not sent at all, the Switch creates a different vposOrderId value with a different orderId value.

• If the orderId field is empty in operation requests where the generateOrderId field is sent "Y", sent empty, or not sent at all, an orderid and a vposOrderID value are generated.

• In transaction requests where the generateOrderId field is sent "N", the orderId value of the transaction and the vposOrderId value will be the same.

• In the order inquiry service, the value in the orderId field returned as a result of the primary transaction should always be sent

Card Storage and Switch Return Codes and Explanations

The return-reason codes to be returned from the Card Storage and Switch system and their descriptions are given in the table below.

Code Examples

Below are links to custom code examples written in various programming languages. You can examine in detail the code written in your preferred programming language with predefined values.

These examples contain code for the relevant type of operation and since they are written in different languages, you can 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 here for C# Code Examples.

Click here 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 you may need to take necessary adaptation and security measures to use them in real projects.

Test Cards

You can find the list of test cards on this page.