• Switch

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:

Title Value 
Switch ID: CC82C381E078482AB328943FCCB7100C
Switch Password : 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. 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:

\"header\": { \n \"requestId\": \"unique_request_id\", \n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\", \n \"userId\": \"your_user_id\", \n \"timestamp\": \"15032021151020\", \n \"hashedData\": \"This should be the calculated hash value\" \n} \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: 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

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} \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} \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: 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:

requestId = \"ba0e96080c7b4216847ef71197d4ad06\" \nswtId = \"CC82C381E078482AB328943FCCB7100C\" \nreturnCode = \"00\" \nreasonCode = \"00\" \nmessage = \"Success\" \ntimestamp = 1615734734018 (Unix Timestamp value) \nSwitch Password = \"123asdASD@\" \n \nIf these values are used for HashedData calculation: \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.

Pre-Authorization Shutdown (Postauth) Requests

Preauthorization closure (postauth) for transactions sent as pre-authorization (preauth)

request is initiated. With pre-authorization closing (postauth), the transaction amount is reflected in the provision.

By giving the requestId of the pre-authorization (preauth) transaction in the Switch application, pre-authorization closing (postauth) transactions can be triggered by merchants with API.

Parameters to be sent to the Service

The parameters that must be sent to the Pre-Authorization Closing service in addition to the Request Header tag are as follows:

Cardholder Information

Field Type Requirement Lenght Description
customerNumber String No Max                  20 Characters Garanti Bank customer number.
email String Field Max                128 Characters Customer e-mail address information.
gsm String No Max                  16 Characters Customer cell phone number information.
ip String Yes Max                  20 Characters Customer IP address information. It must be sent in ipv4 format.
lastName String No Max                  50 Characters Customer last name information.
name String No Max                  50 Characters Customer first name information.
nationalNumber String No Max                  20 Characters Customer ID number information.

Transaction Information

Field Type Requirement Lenght Description
originalRequestId String Yes Max                  36 Characters Request ID of the transaction for which pre-authorization closure is requested.
txnAmount String Yes - Amount of the transaction for which pre-authorization closure is requested. Penny information will be separated with a period. Example : 1.45

Environment API Extensions

Testbed Link:\nhttps://gbtaksimtunel-integration.garanti.com.tr/api/payment/postauth\n\nProduction Environment Link:\nhttps://kartsaklamabackend.garanti.com.tr/api/payment/postauth\n

Json Request Example

{\n \"acquirer\": {\n \"bankId\": \"\"\n },\n \"cardHolder\": {\n \"customerNumber\": \"\",\n \"email\": \"your@mail.com\",\n \"gsm\": \"5554443322\",\n \"ip\": \"1.1.1.1\",\n \"lastName\": \"LastName\",\n \"name\": \"name\",\n \"nationalNumber\": \"11111111111\"\n },\n \"txnAmount\": \"300\",\n \"header\": {\n \"hashedData\": \"1E08970CBFE2D580BA62837231ECE3EA8B31F56D09DEB8B0EA88FA276FB18841 \",\n \"requestId\": \"ornekrequestid_postauth_request_4\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"timestamp\": \"31052019002\",\n \"userId\": \"PROVAUT\"\n },\n \"originalRequestId\": \"ornekrequestid_preauth_request_1\"\n}\n

Json Request Response Example

{\n \"header\": {\n \"requestId\": \"ornekrequestid_postauth_request_4\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Success\",\n \"timestamp\": \"2021-09-03T08:52:20.483+0000\",\n \"hashedData\": \"153EEC5D24A90516C2767229DCF344298F6B0E2688C4C10AED4E1BBE89F2D6CD \"\n },\n \"orderId\": \"ornekorderid_preauth\",\n \"txnAmount\": 300,\n \"installmentCount\": 0,\n \"acquirerId\": \"62\",\n \"acquirerResponse\": {\n \"terminalId\": \"30690168\",\n \"merchantId\": \"7000679\",\n \"orderId\": \"ORDR1D73AAF4A3684C35AF934A6A5F4FAEAB\",\n \"orderGroupId\": \"\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"errorMessage\": \"\",\n \"retRefNum\": \"124606082548\",\n \"authCode\": \"796167\",\n \"provisionDate\": \"20210903 11:52:20\",\n \"extraData\": {\n \"mode\": \"\",\n \"terminal.provUserID\": \"PROVAUT\",\n \"terminal.userID\": \"PROVAUT\",\n \"terminal.id\": \"30690168\",\n \"terminal.merchantID\": \"7000679\",\n \"customer.ipAddress\": \"1.1.1.1\",\n \"customer.emailAddress\": \"\",\n \"order.orderID\": \"ORDR1D73AAF4A3684C35AF934A6A5F4FAEAB\",\n \"order.groupID\": \"\",\n \"transaction.response.source\": \"HOST\",\n \"transaction.response.code\": \"00\",\n \"transaction.response.reasonCode\": \"00\",\n \"transaction.response.message\": \"Approved\",\n \"transaction.response.errorMsg\": \"\",\n \"transaction.response.sysErrMsg\": \"\",\n \"transaction.retrefNum\": \"124606082548\",\n \"transaction.authCode\": \"796167\",\n \"transaction.batchNum\": \"005018\",\n \"transaction.sequenceNum\": \"000009\",\n \"transaction.provDate\": \"20210903 11:52:20\",\n \"transaction.cardNumberMasked\": \"375622******013\",\n \"transaction.cardHolderName\": \"\",\n \"transaction.cardType\": \"AMEXE\",\n \"transaction.hashData\": \"E66CA2DAAFD36C4204A52F5C17C36356896901F4\",\n \"transaction.hostMsgList\": {},\n \"transaction.rewardInqResult.rewardList.reward\": [],\n \"transaction.rewardInqResult.chequeList\": {}\n }\n },\n \"vposOrderId\": \"ORDR1D73AAF4A3684C35AF934A6A5F4FAEAB\"\n}\n

Pre-Authorization Procedures Answer

Field Type Description
orderId String Order information sent in the request message.
orderGroupId String The group information of the order sent in the request message.
vposOrderId String The orderid value generated by Sw itch if generateOrderId was sent as Y or empty in the request message, or if this field was not sent at all.
acquirerId String POS bank ID where the transaction was sent.
txnAmount String Transaction amount.
installmentCount Integer Number of installments sent in the transaction.

Acquirer Response (Response Returned by Virtualpos)

Field Type Description
terminalId String Virtualpos terminal information where the transaction is processed.
merchantId String Merchant number information of the transaction.
orderId String Order number information of the transaction.
orderGroupId String Order group number of the transaction.
returnCode String Transaction result code.
reasonCode String Transaction reason code.
errorMessage String If there is an error in the transaction, what it is will be communicated in this field.
retRefNum String The retref number of the transaction.
authCode String The auth code returned by Sanalpos.
provisionDate String Provision date of the transaction.
extraData Map<String, Object> It is the data transmitted additionally by Sanalpos.

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:

{ \n \"header\" : { \n \"requestId\" : \"f51af3e152b448fa84b84331f95ee783\", \n \"swtId\" : \"CC82C381E078482AB328943FCCB7100C\", \n \"returnCode\" : \"11\", \n \"reasonCode\" : \"1100\", \n \"message\" : \"Request validation error, see errorMap for details\", \n \"timestamp\" : 1616089736577, \n \"hashedData\" : \n\"4F1977ED2F17E2DD60BC283A1BAF0DF09ED759D0BB2589A150493AE8A2CF4243 \n\" }, \n \"errorMap\" : { \n \"additionalData\" : \"Maximum number of characters that can be sent: 128\", \n \"card.expireMonth\" : \"Number of characters to send: 2\", \n \"card.expireYear\" : \"Number of characters to send: 2\" \n } \n} \n

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.

Refund Code  Reason Code (Sub-Return Code)  Description 
00 00 The transaction was successful. 
01 01 This error is received when the Acquirer does not validate the discarded transaction. For example, this error will be received in a case where the sales request fails or the validation fails in the 3D HTML request. The order query service returns the error code 01 in the header for failed transactions in the query response. 
01 02 The order inquiry service returns for transactions that do not have virtualpos in the query response. Reason Code 01, not 02, will be returned for canceled transactions that could not be forwarded to Nestpay virtualpos. 
02 04 The order inquiry service returns for 3D transactions for which there is no sanalposta in the query response. When this answer is received, it is possible that the 3D transaction has not been completed yet, so a new query can be sent. The query can be sent until Reason Code 00 or 01. However, if the cardholder has abandoned the transaction and it has not been finalized, the Reason Code will always remain 04. 
03 03 Virtualpos requested to send a request cannot be processed 
10 1000 Invalid http request type. This error is received when the system cannot read the incoming http request. 
11 1100 Request validation error. The errorMap returned in the response contains the details of the error. It is necessary to edit according to the instructions here. 
12 1200 The transaction could not be performed with the orderId value found in the transaction. A request should be made with a new orderId. 
12 1201 The exchange rate in the request is not the same as the exchange rate in the order. 
12 1202 Valid order not found error. The order information to be processed is not available in the system. For example, this error is received if a cancellation or return is sent for a transaction that is not sold. 
13 1300 No valid transaction found error. The transaction information to be processed is not available in the system. For example, if there is an order in the request, but the transaction could not be found, it will give this error. 
13 1301 Invalid transaction type. The transaction being attempted is not allowed. For example, a return request can only be applied to transactions with a sale. This error is received if a return request is sent to a different transaction type than the original sale. This also applies to a cancel request. 
13 1302 This error is received if a cancel or refund request is sent for a failed sale. 
31 3101 The virtualpos response could not be processed by Switch. 
67 6700 Encryption error. Generally a temporary error. It is necessary to try several operations again. In case it happens too often, please contact ETicaretDestek@garantibbva.com.tr. 
78 109 To get the token you need to send (full card + skt) or (first 6 - last 4 and customer/ID number). 
78 300 An error was encountered while encrypting the card during the token request. The transaction should be tried again. 
78 401 The token could not be generated because the status of the card sent in the token request was not available for authorization. The status of the card should be checked. 
78 402 The status of the token request card is not available for token retrieval. The status of the card should be checked. 
78 500 No valid parameter definition found during token request. A parameter definition is required for the sw tId sent in the request. For this, please contact ETicaretDestek@garantibbva.com.tr. 
78 500 Token not found. The sent token information should be checked. There may be an attempt to make a transaction with a deleted token. 
78 99 General error. In some cases it may be temporary. In case it is received too often, ETicaretDestek@garantibbva.com.tr can be contacted. 
83 8300 Data error. The data in the request sent should be checked. If the problem is not detected, the E-Commerce Support team should be contacted. 
99 99 System error. In some cases it may be temporary. If it is received too often, ETicaretDestek@garantibbva.com.tr can be contacted. 

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. 

We would love to hear from you. Do you have problems/questions about services ? Send us detailed email about it ?

Send Us a Question Send Us a Question