-
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.
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 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 GarantiBBVA Switch integration.
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 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:
hashedData = UPPERCASE(SHA256(swtId & orderId & txnType & txnAmount &\ntxnInstallmentCount & successUrl & failureUrl & txnTimestamp & txnCurrencyCode\n& switchPassword))\nSample Data :\nswtid : CC82C381E078482AB328943FCCB7100C\norderId : unique_order_id\ntxnType : sales\ntxnAmount : 1.45\nxnInstallmentCount : 0\nsuccessUrl : https://garantibbvapos.com.tr/destek/postback.aspx\nfailureUrl : https://garantibbvapos.com.tr/destek/postback.aspx\ntxnTimestamp : 18032021222930\ntxnCurrencyCode : 949\nswitchPassword : 123asdASD@\n\nhashedData = UPPERCASE(SHA256(CC82C381E078482AB328943FCCB7100Cunique_order_idsales1.450\nhttps://garantibbvapos.com.tr/destek/postback.aspxhttps://garantibbvapos.com.tr/destek/postback.aspx18032021222930949123asdASD@))\n\nhashedData = 896F569528570C0735D319F9EA16B465B89EDC2E91362A28DD6D130FFCA728C8\n
Hash Calculation for 3D Service Responses
The response form sent to the merchant after the 3D payment is received will also contain a field named hashedData. Merchant can check the validity of the incoming data by generating the value in the hashedData field using the following fields returned in the 3D response form. The Response hash can be obtained by concatenating some fields side by side as String, concatenating the Switch user password to the end of the String, hashing it with the SHA256 algorithm and converting it to uppercase letters, just like the Request hash. The method and example are as follows:
hashedData = UPPERCASE(SHA256(requestId & swtId & returnCode & reasonCode &\nmessage & switchPassword))\n\nSample Data :\nrequestId : 01032021191812\nswtId : CC82C381E078482AB328943FCCB7100C\nreturnCode : 00\nreasonCode : 00\nmessage : Successful\nswitchPassword : 123asdASD@\n\n3D Response Hash Calculation with Sample Data:\nhashedData = UPPERCASE(SHA256(01032021191812CC82C381E078482AB328943FCCB7100C0000B\nsuccessful123asdASD@))\n\nhashedData = 5A9AAE6D755B8662042C02A2645108F4998EAFA2E8DF52121A259ADBF26877E0\n
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.
