-
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.
Payment Requests
Merchants send payment requests for sales, sales in installments, pre-authorization and pre-authorization in installments transactions to more than one bank Virtual PoS using the APIs offered by the Switch application with stored card data or open card data. As a result of the payment request, the amount specified in the transaction is collected from the relevant card and entered at the end of the day. Merchants are expected to enter PoS Credential information for the banks they are currently using under the Bank Identification menu in the Switch Management Screens before sending requests to the payment APIs in the production environment. After this step, the Switch system stores the values defined by the merchant for each bank in the system in encrypted form. Smart Switch system decides which bank to send payment request to in the transaction initiated by the merchant by triggering the API and prepares the sales form with the bank credential information stored encrypted in the system and ensures that it is sent on behalf of the merchant.
With the Smart Switch system;
- Based on the bank ID sent by the merchant in the API, a payment request can be sent directly to the relevant bank.
- If the merchant does not send a bank ID in the api, a payment request can be sent to the bank of the transaction card.
- If the merchant does not send a bank ID in the API and the bank of the card being processed is not an integrated bank in the Switch system, a payment request can be sent via the bank that the merchant defines as default.
- If the default bank is not defined, a request can be sent to any of the defined banks.
Parameters to be sent in Payment Requests
Although the API addresses to make requests for card authorization (card sale) and token authorization (token sale) are different, the request-response message structure is the same for both APIs. The only difference in the request messages is that the token information is sent instead of the card number in token requests.
The parameters that should be sent to authorization and token and authorization services in addition to the Request Header tag are as follows:
Acquirer Bank Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| bankId | String | No | - | This field is used if the transaction is to be sent through the VirtualPOS of a specific bank. Value that can be sent: Bank Code and Name: 64: İŞ BANK A.Ş. 62: T.GARANTİ BANKASI A.Ş. 46: AKBANK T.A.Ş. 111: QNB FINANSBANK A.Ş. 10: T.C. ZİRAAT BANKASI A.Ş. 12: T. HALK BANKASI A.Ş. |
Card Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| cvv | String | No | 3 Character | The 3-digit number on the back of the card. |
| expireMonth | String | Yes if the Card Sales API is used | 2 Character | The month on the card. |
| expireYear | String | Yes if the Card Sales API is used | 2 Character | The year on the card. |
| first6 | String | No | 6 Character | First 6 digits of the card. |
| holderName | String | No | Max 50 Character | The name on the card. |
| last4 | String | No | 4 Character | Last 4 digits of the card. |
| number | String | Yes if the Card Sales API is used | Min : 15 CharacterMax : 30 Character | Card number. |
| token | String | Yes if Sales API is used with Stored Card (Token) | 32 Character | TokenID information associated with the card returned as a result of the Token Import transaction. |
Transaction Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| txnAmount | String | Yes | - | Transaction amount. It is necessary to separate the penny information with a period. Example : 1.45 |
| currencyNumber | String | Yes | 3 Character | Exchange rate information. 3 digit ISO standard codes must be sent. Example : 949 |
| installmentCount | String | Yes if sending installment transactions | Max 3 Character | If an installment transaction will be sent, the number of installments should be sent in this field. For example; it should be sent as '3' for 3 installment transactions. |
| motoInd | String | Yes if sending MOTO transaction | 1 Character | If Mail / Phone order transaction is sent, it should be marked as 'Y'. |
| orderId | String | No | Max 36 Character | The order number of the transaction. It must be specific to each transaction. |
| orderGroupId | String | No | Max 36 Character | Order group number of the transaction. |
| generateOrderId | String | No | 1 Character | "N" should be sent if the merchant wants the orderId sent in the transaction to be forwarded to the virtual exchange, and "Y" should be sent if Sw itch wants to generate a new orderId that matches the orderId structure of the virtual exchange to which the transaction will be forwarded. The Sw itch will generate a new orderId even if the field is not sent at all or the value is blank. |
| additionalData | String | No | Max 120 Character | If an additionalData value is sent with the token in the sale request, it is checked whether the token can be used for that additionalData, and the decision whether to continue provisioning is based on whether the value is the same as the value at the time the token was received. |
Cardholder Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| customerNumber | String | No | Max 20 Character | Garanti Bank customer number. |
| String | Yes | Max 128 Character | Customer e-mail address information. | |
| gsm | String | No | Max 16 Character | Customer cell phone number information. |
| ip | String | Yes | Max 20 Character | Customer IP address information. It must be in IPv4 format. |
| lastName | String | No | Max 50 Character | Customer surname information. |
| name | String | No | Max 50 Character | Customer name information. |
| nationalNumber | String | No | Max 20 Character | Customer ID number. |
Invoice Address Detail Information
| Field | Tyğpe | Requirement | Length | Description |
|---|---|---|---|---|
| addressDetail | String | No | Max 256 Character | Invoice address details (District, neighborhood, street, door code etc.). |
| city | String | No | Max 50 Character | City to send invoice to. |
| companyName | String | No | Max 64 Character | Company information to send invoice to. |
| country | String | No | Max 50 Character | Country to send invoice to. |
| String | Yes | Max 128 Character | The e-mail address of the person to whom the invoice will be sent. | |
| gsm | String | No | Max 16 Character | Cell phone number of the person to whom the invoice will be sent. |
| lastName | String | No | Max 50 Character | Last name of the person to whom the invoice will be sent. |
| name | String | No | Max 50 Character | Name of the person to whom the invoice will be sent. |
| phone | String | No | Max 36 Character | Telephone number associated with the place where the invoice will be sent. |
| zipCode | String | No | Max 16 Character | The postal code of the address to which the invoice will be sent. |
Cargo Address Detail Information
| Field | Type | Requirement | Length | Description |
|---|---|---|---|---|
| addressDetail | String | No | Max 256 Character | Cargo address details (District, neighborhood, street, door code etc.). |
| city | String | No | Max 50 Character | Shipping city information. |
| companyName | String | No | Max 64 Character | Shipping company information. |
| country | String | No | Max 50 Character | Shipping country information. |
| String | Yes | Max 128 Character | The e-mail address of the person to whom the cargo will be sent. | |
| gsm | String | No | Max 16 Character | Cell phone number of the person to whom the cargo will be sent. |
| lastName | String | No | Max 50 Character | Surname of the person to whom the cargo is to be sent. |
| name | String | No | Max 50 Character | The name of the person to whom the parcel will be sent. |
| phone | String | No | Max 36 Character | Telephone information associated with the place where the cargo will be sent. |
| zipCode | String | No | Max 16 Character | The postal code of the address to which the cargo will be sent. |
Environment API Extensions
Testbed Link:\nhttps://gbtaksimtunel-integration.garanti.com.tr/api/payment/auth\n\nProduction Environment Link:\nhttps://kartsaklamabackend.garanti.com.tr/api/payment/auth
Json Request Example
{\n \"subType\": \"\",\n \"txnAmount\": \"10.50\",\n \"generateOrderId\": \"Y\",\n \"currencyNumber\": \"949\",\n \"installmentCount\": \"0\",\n \"orderId\": \"f0553df546cb4e41957f9f225cb7d88e\",\n \"orderGroupId\": \"\",\n \"card\": {\n \"number\": \"5549601449497017\",\n \"expireMonth\": \"02\",\n \"expireYear\": \"25\"\n },\n \"acquirer\": {\n \"bankId\": \"62\"\n },\n \"cardHolder\": {\n \"name\": \"\",\n \"lastName\": \"\",\n \"gsm\": \"5555555555\",\n \"email\": \"user@mail.com\",\n \"ip\": \"192.168.1.1\",\n \"nationalNumber\": \"\",\n \"customerNumber\": \"\"\n },\n \"billingAddress\": {\n \"name\": \"name\",\n \"lastName\": \"lastName\",\n \"companyName\": \"GT\",\n \"city\": \"Istanbul\",\n \"country\": \"Turkey\",\n \"zipCode\": \"34000\",\n \"addressDetail\": \"Work Address\",\n \"phone\": \"2165555555\",\n \"gsm\": \"5555555555\",\n \"email\": \"your@mail.com\"\n },\n \"shippingAddress\": {\n \"name\": \"name\",\n \"lastName\": \"lastName\",\n \"companyName\": \"GT\",\n \"city\": \"Istanbul\",\n \"country\": \"Turkey\",\n \"zipCode\": \"34000\",\n \"addressDetail\": \"Work Address\",\n \"phone\": \"2165555555\",\n \"gsm\": \"5555555555\",\n \"email\": \"your@mail.com\"\n },\n \"moto\": \"\",\n \"header\": {\n \"requestId\": \"306d5b87639a4ed9971bf5537c9d8177\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"hashedData\": \"73F3AAC513E5BA394C7027DF0102D2EE9C09C404E6DC357E754DA326E607E927 \",\n \"timestamp\": \"2021-03-17T17:56:56.575Z\"\n }\n}
Json Request Response Example
{\n \"orderId\": \"f0553df546cb4e41957f9f225cb7d88e\",\n \"orderGroupId\": \"\",\n \"txnAmount\": \"10.50\",\n \"installmentCount\": \"0\",\n \"card\": {\n \"binNumber\": \"554960\",\n \"bankId\": \"\",\n \"maskedNumber\": \"554960******7017\",\n \"bankName\": \"\"\n },\n \"acquirerId\": \"62\",\n \"acquirerResponse\": {\n \"terminalId\": \"30690168\",\n \"merchantId\": \"7000679\",\n \"orderId\": \"f0553df546cb4e41957f9f225cb7d88e\",\n \"orderGroupId\": \"\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"errorMessage\": \"\",\n \"retRefNum\": \"107603475302\",\n \"authCode\": \"928892\",\n \"provisionDate\": \"20210317 20:56:58\",\n \"extraData\": {\n \"mode\": \"\",\n \"terminal.provUserID\": \"PROVAUT\",\n \"terminal.userID\": \"PROVAUT\",\n \"terminal.id\": \"30690168\",\n \"terminal.merchantID\": \"7000679\",\n \"customer.ipAddress\": \"192.168.1.1\",\n \"customer.emailAddress\": \"\",\n \"order.orderID\": \"f0553df546cb4e41957f9f225cb7d88e\",\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\": \"107603475302\",\n \"transaction.authCode\": \"928892\",\n \"transaction.batchNum\": \"004701\",\n \"transaction.sequenceNum\": \"000367\",\n \"transaction.provDate\": \"20210317 20:56:58\",\n \"transaction.cardNumberMasked\": \"554960******7017\",\n \"transaction.cardHolderName\": \"UT** ER***\",\n \"transaction.cardType\": \"BONUS\",\n \"transaction.hashData\": \"2F2914B483BD851D85CBC35531FDAEEBAB17FB88\",\n \"transaction.hostMsgList.hostMsg\": \"TEBRIKLER 34748 NO.LU KAMPANYADAN KAZANDINIZ\",\n \"transaction.rewardInqResult.rewardList.reward[0].type\": \"FBB\",\n \"transaction.rewardInqResult.rewardList.reward[0].totalAmount\": \"0\",\n \"transaction.rewardInqResult.rewardList.reward[0].lastTxnGainAmount\": \"1500\",\n \"transaction.rewardInqResult.chequeList\": {}\n }\n },\n \"header\": {\n \"requestId\": \"306d5b87639a4ed9971bf5537c9d8177\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1616003819589,\n \"hashedData\": \"5924AD07C74D92E2EB4DB2BAFCAEA0C6135AA893638DDBD01532FA1605598FB E\"\n },\n \"vposOrderId\": \"ORDRDB32ADBC6B804E33A6A80B67F6A00F72\"\n}
Payment Transactions 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. |
| txnAmount | String | Transaction amount. |
| installmentCount | String | Number of installments sent in the transaction. |
| acquirerId | String | POS bank ID where the transaction was sent. |
Card Information
| Field | Type | Description |
|---|---|---|
| binNumber | String | First 6 digits of the card number. |
| maskedNumber | String | Masked card number information. |
| bankName | String | The bank to which the card belongs. |
| token | String | If it is a request sent with a token, the Token ID information is returned in this field. |
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 Virtualpos.. |
| provisionDate | String | Provision date of the transaction. |
| extraData | Map<String, Object> | It is the data transmitted additionally by Virtualpos. |
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.
