-
Virtual POS
Virtual POS Transactions General Concepts
Garanti Virtual POS is a secure payment solution created to receive credit card payments for online sales.
Merchants can open an online branch in their stores and turn it into a sales platform that never closes with Garanti Virtual POS. This contributes to increasing both the number of customers and turnover.
The following transactions are generally performed under Garanti Virtual POS:
- Sales Transactions
- Common Payment Page Operations
- Cancellation Transactions
- Refund Transactions
- Closing Procedures
- Inquiry Transactions
In this document, the steps required for merchants to be able to provide non 3Ds Cancel transactions under Garanti Virtual POS, the operations to be performed within each step, and the structures of the transaction requests sent and response messages received are explained.
Virtual POS Cancellation Procedures
Cancellation is an action taken to invalidate a transaction during the day.
Transactions can be canceled on the same day. If the transaction needs to be canceled for the following days, the transaction to be made is a return.
There is no reversal of a cancel transaction. For this reason, if a cancellation is made by mistake, then the canceled transaction must be made again.
Cancellations do not create a trace on the card. They do not appear on card statements or in-period transactions.
3D Concept
3D Secure is a version of the application on VirtualPoS where cardholders are verified with a password on PoS. The cardholder is directed to the verification screens of the card bank to use a password in the transaction. The cardholder enters the information requested by his/her bank on these screens and shows that the card actually used is his/her own card.
After verification, the verification status is returned to the merchant bank (merchant). Then, depending on the status of the 3D information, the authorization process is carried out or the transaction is terminated.
3D Secure is supported by Master, Visa and American Express (Amex) cards. Merchants using 3D model (information about merchant models is given below) are required to come directly to provisioning without performing 3D verification for cards other than Mastercard, Visa and Amex. Since 3D secure is not supported, the responsibility for Fraud in such transactions belongs to the merchant. The merchant must take measures to protect itself.
Virtual POS Transactions Non 3ds
This is when the transaction is concluded without touching any 3D secure stage during the authorization flow. In this type of transaction, the customer's "I didn't do it" objections turn into a chargeback request. The chargeback process is evaluated by requesting evidence from the merchant that the transaction was made by the customer. In 3D transactions, "I did not do it" requests are terminated by the bank in transactions with successful verification.
Test / Prod Environment Selections:
For Virtual POS Sales transactions, it is possible for the merchant to proceed with 2 different methods. If the merchant wishes, they can make all the improvements in the Test environment. Alternatively, the necessary developments for these transactions can be made directly in the broadcast environment.
According to the method to be chosen by the merchant, before starting Virtual POS sales transactions, the first transactions must be made according to the appropriate one of the following headings:
If the work to be done is carried out in a test environment, the following predefined values can be used as they are:
| Parameter | Value |
|---|---|
| MerchantID | 7000679 |
| ProvUserID | PROVAUT / PROVRFN / PROVOOS |
| ProvisionPassword | 123qweASD/ |
| TerminalID | 30691297 |
In the studies to be carried out in the test environment "https://sanalposprovtest.garantibbva.com.tr/VPServlet" url'i will be used.
A panel where the operations performed in the test environment can be monitored and displayed at this address you can access.
| Variable | Value |
|---|---|
| User Name | 99999999999 |
| Password | Destek.1 |
| Code | 147852 |
Not: In the event of an error in the password process, please try a second time before making a second attempt. Send Us a Question Please provide information with the form.
List of all test cards that can be used in the test environment from this page you can reach.
When proceeding with this method, the passwords to be used by the merchant in the setup as the first step are (“PROVAUT”,“PROVOOS”, “PROVRFN” ve “3D” (storekey) şifreleri) Virtual POS First Steps virtual POS management panel as specified in the document.
Passwords and accounts created in this way will be used in the next steps.
In the studies to be carried out in PROD environment "https://sanalposprov.garantibb.com.tr/VPServlet" url'i will be used.
Hash Algorithm
This document explains step by step how to create the data required for the <HashData> tag in the request message, which is used under many transaction types.
The <HashData> tag in the request messages is the field that allows the password verification of the user. Hash creation details are explained separately below.
In the new VirtualPoS application, the HASH structure is used to prevent the password of the terminal from circulating openly.
Hash account:
1. SHA1 in the calculation of hashedpassword information
2. SHA512 algorithm is used to calculate the hashvalue.
In the hash calculation, a two-part HASH structure is used. In the first stage, the hashedpassword value will be obtained using the SHA1 algorithm by juxtaposing the provisioning password with the terminal number.
The operations required to generate hash are presented below for different programming languages:
public static string Sha1(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA1CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string Sha512(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA512CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string GetHashData(string userPassword, string terminalId, string orderId, string cardNumber, ulong amount, int currencyCode) {\n var hashedPassword = Sha1(userPassword + terminalId);\n return Sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword).ToUpper();\n}
Public Shared Function Sha1(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA1CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function Sha512(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA512CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function GetHashData(ByVal userPassword As String, ByVal terminalId As String, ByVal orderId As String, ByVal cardNumber As String, ByVal amount As ULong, ByVal currencyCode As Integer) As String\n Dim hashedPassword = Sha1(userPassword & terminalId)\n Return Sha512(orderId & terminalId & cardNumber & amount & currencyCode & hashedPassword).ToUpper()\nEnd Function
public static String calculateHash(String data, String algorithm, String charset) throws UnsupportedEncodingException, NoSuchAlgorithmException {\n\tMessageDigest md = MessageDigest.getInstance(algorithm);\n\tbyte[] databytes = data.getBytes(charset);\n\t\n\tmd.update(databytes);\n byte[] hashBytes = md.digest();\n \n return byteArray2HexaDecimal(hashBytes);\n}\n\npublic static String sha1(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-1\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String sha512(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-512\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String getHashData(String userPassword, String terminalId, String orderId, String cardNumber, Long amount, int currencyCode) {\n var hashedPassword = sha1(userPassword + terminalId);\n return sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword);\n}
private function GenerateSecurityData($terminalId)\n {\n $password = \"password\";\n\n $data = [\n $password,\n str_pad((int)$terminalId, 9, 0, STR_PAD_LEFT)\n ];\n\n $shaData = sha1(implode('', $data));\n\n return strtoupper($shaData);\n }\n\n public function GenerateHashData()\n {\n $orderId = \"order_id\"; //must be uniqe\n $terminalId = \"terminal_id\"; //must be integer\n $cardNumber = \"1234123412341234\"; //card number\n $amount = \"100\"; //amount\n $currencyCode = \"currency_code\"; //must be int\n\n $hashedPassword = GenerateSecurityData($terminalId);\n\n $data = [\n $orderId, $terminalId, $cardNumber, $amount, $currencyCode, $hashedPassword\n ];\n \n $shaData = strtoupper(hash(\"sha512\", implode('', $data)));\n\n return strtoupper($shaData);\n }
Request Structure
The request structure required for all non 3Ds Virtual POS transactions is specified in the table below. The information and explanations required for each tag under the main tag in the first column in the table should be examined and the request message should be provided according to the rules specified in this table:
<?xml version=\"1.0\" encoding=\"iso-8859-9\"?>\n<GVPSRequest>\n\t<Mode>TEST</Mode>\n\t<Version>512</Version>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\n\t\t<HashData>D1AC6A68685850B3125F241C340C50135B4B5945A9051140B5907237AA37C5DDBB18044F1DC3FDAB44EB1886D2096AF29202633F34320D43E10B630676BE82FB</HashData>\n\t\t<UserID>PROVAUT</UserID>\n\t\t<ID>30691297</ID>\n\t\t<MerchantID>7000679</MerchantID>\n\t</Terminal>\n\t<Customer>\n\t\t<IPAddress>192.168.0.1</IPAddress>\n\t\t<EmailAddress>eticaret@garanti.com.tr</EmailAddress>\n\t</Customer>\n\t<Card>\n\t\t<Number>4824892453725018</Number>\n\t\t<ExpireDate>0125</ExpireDate>\n\t\t<CVV2>567</CVV2>\n\t</Card>\n\t<Order>\n\t\t<OrderID>447ce60366b24dddada4c5324460ddb8</OrderID>\n\t\t<GroupID />\n\t</Order>\n\t<Transaction>\n\t\t<Type>preauth</Type>\n\t\t<ListPageNum>0</ListPageNum>\n\t\t<Amount>100000</Amount>\n\t\t<CurrencyCode>949</CurrencyCode>\n\t\t<CardholderPresentCode>0</CardholderPresentCode>\n\t\t<MotoInd>N</MotoInd>\n\t</Transaction>\n</GVPSRequest>
Within this structure, many tags contain sub-tags within themselves. Under the relevant heading where each tag is described, the usage rules of tags without subtags and the details of tags with subtags are presented in a separate heading.
| Bottom Label | Max Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <Mode> | PROD | This is the field where the process mode is written | |
| <Version> | 16 byte | Format zorunluluğu yok | This is the field where the Api version used is written. Within the scope of hash calculation as Sha512, 512 value must be sent in this field. |
| <Terminal> | In order to provide virtual pos verification, parameters such as virtual pos number user information are sent. This tag contains sub tags. The tags and rules it contains are given in the following headings. | ||
| <Customer> | This is the field where Customer Information is sent. It is mandatory to send the information in the tag. There are sub tags in this tag. The tags and rules it contains are given in the following headings. | ||
| <Order> | This is the field where information and details of the order are sent. There are sub tags in this tag. The tags and rules it contains are given in the following headings. | ||
| <Transaction> | This is the field where transaction and financial information is sent. There are sub tags in this tag. The tags and rules it contains are given in the following headings. |
<Terminal> Tag and the Tag to be placed under it and its Details
Virtual such as virtual pos number user information to ensure pos verification parameters are sent.
<Terminal>\n\t<ProvUserID></ProvUserID>\n\t<HashData></HashData>\n\t<UserID></UserID>\n\t<ID></ID>\n\t<MerchantID></MerchantID>\n</Terminal>
The sub-tags within this tag and their details are given below:
| Bottom Label | Max Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <ProvUserID> | 32 byte | No format requirement | This is the field where the provision user code of the terminal is sent. Prov user, Cancel refund user or OOS user can be found here |
| <HashData> | 32 byte | Hash algorithm SHA512 format. After hash conversion, lower case letters must be converted to upper case. Details are given below. | This is the field where the user's password verification is performed. Hash creation details are explained separately in this document. |
| <UserID> | No format requirement | This is the field where the user who made the transaction (Agent - Sales Representative) is sent. | |
| <ID> | 9 byte | Nümerik | The field where the terminal number is sent |
| <MerchatID> | 9 byte | Nümerik | This is the field where the workplace number is sent. |
<Customer> Tag and Rules for the <Customer> Tag and Tags Below it
This is the field where Customer Information is sent. It is mandatory to send the information in the tag.
<Customer>\n <IPAddress></IPAddress>\n <EmailAddress></EmailAddress>\n</Customer>
| Bottom Label | Max Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <IPAdress> | 20 byte | No format requirement | This is the field where the IP address of the customer who made the transaction is sent. It must be sent compulsorily in order to ensure fraud controls. |
| <EmailAddress> | 64 byte | This is the field where the E-Mail address of the customer who made the transaction is sent. |
<Order> Tag Label and Rules for the <Order> Tag
This is the field where the information and details of the order are sent in the request.
<Order>\n <OrderID></OrderID>\n <GroupID></GroupID>\n</Order>
| Bottom Label | Data Writing Format | Description and notes |
|---|---|---|
| <OrderID> | Alfanümerik | This is the field where the order number is returned. |
| <GroupID> | Alfanümerik | The field where the GroupID number is returned. This tag contains sub tags. Details about the sub tags are given in the headings below. |
<Transaction> Tag and its Rules
This is the field where transaction information and financial information are sent in the request message in partial cancellation transactions Non 3ds.
<Transaction>\n\t<Type></Type>\n\t<ListPageNum></ListPageNum>\n\t<Amount></Amount>\n\t<CurrencyCode></CurrencyCode>\n\t<OriginalRetrefNum></OriginalRetrefNum>\n\t<CardholderPresentCode></CardholderPresentCode>\n\t<MotoInd></MotoInd>\n</Transaction>
| Bottom Label | Max Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <Type> | 32 byte | Alfanümerik | This is the field where the Transaction Type is sent. Details about transaction types will be given separately in the document. Attention should be paid to the use of other fields according to the transaction type. |
| <ListPageNum> | |||
| <Amount> | 17,2 number | The numeric is sent as LLLLLLKK. The last 2 digits represent cents. 1,00 TL -> 100 11,22 TL->1122 0,01TL -> 1 | This is the field where the amount information is entered. If the transaction is a "Partial Refund" transaction, the amount entered in this field is refunded. |
| <CurrencyCode> | 3 byte | Nümerik | This is the field where exchange rate information is sent. 949 -> TL will be informed for other exchange rates according to your authorization. |
| <CardholderPresentCode> | 2 byte | Nümerik | Enter 0 for normal transactions and 13 for 3D transactions. |
| <MotoInd> | 1 byte | Alfanümerik | It takes Y and N values. N is sent for Ecommerce transactions. Y is sent for transactions with Moto transaction status. |
Response Structure
For Virtual POS transactions, the response structure returned from the service after the request sent in the previous topics is generally specified in the table below. The information and explanations required for each tag under the main tag in the first column in the table should be examined and the request message should be provided according to the rules specified in this table:
In the Virtual POS cash sales transaction, the response structure is generally as follows:
<GVPSResponse>\n\t<Mode></Mode>\n\t<Terminal></Terminal>\n\t<Customer></Customer>\n\t<Order></Order>\n\t<Transaction></Transaction>\n</GVPSResponse>
The tags in the answer structure given above and the sub tags under these tags are given in the heading below:
| Bottom Label | Data Writing Format | Description and notes |
|---|---|---|
| <Mode> | PROD - TEST | This is the field where the process mode is written |
| <Terminal> | In order to provide virtual pos verification, parameters such as virtual pos number and user information are sent. This tag contains sub parent and child tags within itself. The sub tags it contains are given in the headings below. | |
| <Customer> | This is the area where the customer information sent in the request structure is sent back for verification purposes. This tag contains sub tags within itself. The sub tags it contains are given in the headings below. | |
| <Order> | This is the area where the information and details of the order are sent. This tag contains sub tags within itself. The sub tags it contains are given in the headings below. | |
| <Transaction> | This is the field where transaction and financial information is returned. This tag contains sub parent and child tags within itself. The sub tags it contains are given in the headings below. |
<Terminal> Tag and the Tag to be placed under it and its Details
It is the field where the parameters sent in the request, such as virtual pos number user information, are returned in the response in the same way in order to provide virtual pos verification.
<Terminal>\n\t<ProvUserID></ProvUserID>\n\t<UserID></UserID>\n\t<ID></ID>\n\t<MerchantID></MerchantID>\n</Terminal>
The sub-tags within this tag and their details are given below:
| Bottom Label | Maks Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <ProvUserID> | 32 byte | No format requirement | This is the field where the provision user code of the terminal is sent. Prov user, Cancel refund user or OOS user can be found here |
| <UserID> | No format requirement | This is the field where the user who made the transaction (Agent - Sales Representative) is sent. | |
| <ID> | 9 byte | Nümerik | The field where the terminal number is sent |
| <MerchatID> | 9 byte | Nümerik | This is the field where the workplace number is sent. |
<Customer> Tag and Rules for the <Customer> Tag and Tags Below it
This is the field where the customer information sent in the request is returned in the same way in the response.
<Customer>\n\t<IPAddress></IPAddress>\n\t<EmailAddress></EmailAddress>\n</Customer>
| Bottom Label | Maks Size | Data Writing Format | Description and notes |
|---|---|---|---|
| <IPAdress> | 20 byte | No format requirement | This is the field where the IP address of the customer who made the transaction is sent. It must be sent compulsorily in order to ensure fraud controls. |
| <EmailAddress> | 64 byte | This is the field where the E-Mail address of the customer who made the transaction is sent. |
<Order> Tag Label and Rules for the <Order> Tag
This is the field where the order information sent in the request is returned in the same way in the response.
<Order>\n <OrderID></OrderID>\n <GroupID></GroupID>\n</Order>
| Bottom Label | Data Writing Format | Description and notes |
|---|---|---|
| <OrderID> | Alfanümerik | This is the field where the order number is returned. |
| <GroupID> | Alfanümerik | The field where the GroupID number is returned. This tag contains sub tags. Details about the sub tags are given in the headings below. |
<Transaction> Tag Label and Rules of the <Transaction> Tag
<Transaction>\n <Response></Response>\n <RetrefNum></RetrefNum>\n <AuthCode></AuthCode>\n <BatchNum></BatchNum>\n <SequenceNum></SequenceNum>\n <ProvDate></ProvDate>\n <CardNumberMasked></CardNumberMasked>\n <CardHolderName></CardHolderName>\n <CardType></CardType>\n <HashData></HashData>\n <HostMsgList></HostMsgList>\n <RewardInqResult></RewardInqResult>\n <CampaignChooseLink></CampaignChooseLink>\n <GarantiCardInd></GarantiCardInd>\n</Transaction>
| Bottom Tags | Data Writing Format | Description and notes |
|---|---|---|
| <Response> | This tag contains sub tags. Details about the sub-tags are given in the headings below. | |
| <RetrefNum> | Nümerik | The transaction number generated by Virtualpos is returned |
| <AuthCode> | Nümerik | This is the field where the confirmation code is returned. |
| <BatchNum> | This is the field that returns which batche the transactions will enter. | |
| <SequenceNum> | This is the field where the name of the cardholder is sent. | |
| <ProvDate> | YYYYMMDD | This is the field where the provision date is returned. |
| <CardNumberMasked> | This is the field where the first 6 and last 4 digits of the card number and the fields in between are returned with *. | |
| <CardHolderName> | This is the field where the name of the cardholder is sent. | |
| <CardType> | This is the field where the type of card processed is returned. | |
| <HashData> | This is the field where the HashData information of the transaction is returned. | |
| <HostMsgList> | This tag contains sub tags. Details about the sub-tags are given in the headings below. | |
| <RewardInqResult> | This tag contains sub tags. Details about the sub-tags are given in the headings below. | |
| <GarantiCardInd> | ||
| <CampaignChooseLink> |
<Response> Alt Tags and Descriptions
<Response>\n <Source></Source>\n <Code></Code>\n <ReasonCode></ReasonCode>\n <Message></Message>\n <ErrorMsg></ErrorMsg>\n <SysErrMsg></SysErrMsg>\n</Response>
| Alt Tags | Description and notes |
|---|---|
| <Source> | This is the field where the source information is returned. |
| <Code> | This is the field where Approved - declined information is returned. |
| <ReasonCode> | This is the field where the answer code is returned. |
| <Message> | This is the field where the message information is returned. |
| <ErrorMsg> | This is the field where the error message is returned. |
| <SysErrMsg> | This is the field where the system error message is returned. |
<RewardInqResult> Tag, Subtags and Descriptions
<RewardInqResult>\n<RewardList></RewardList>\n<ChequeList></ChequeList>\n</RewardInqResult>
| Bottom Labels | Data Writing Format | Description and notes |
|---|---|---|
| <RewardList> | This tag contains sub tags. Details about the sub-tags are given in the headings below. | |
| <ChequeList> | This tag contains sub tags. Details about the sub-tags are given in the headings below. |
Code Examples
Below are the github repo links for custom code examples written in different programming languages, including this transaction type. You can examine the codes written with predefined values through the link of your preferred programming language.
- C# For Code Examples click here.
- VB.Net For Code Examples click here.
- For Java Code Examples click here.
- For PHP Code Examples click here.
Error Codes
Error codes from this page you can reach.
Test Cards
List of test cards from this page you can reach.
