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:
This document describes the steps required for merchants to provide non 3Ds Additional Field transactions under Garanti Virtual POS, the operations that must be performed within each step, and the structures of the transaction requests sent and response messages received.
Within the Virtual POS request structure, the request structure can be modified with different additional fields in accordance with different needs. These additional fields and their purposes are briefly explained below.
Address information can be sent to VirtualPoS during the transaction. The information sent is displayed on the order detail pages for information purposes.
Information about the product sold during the purchase can be sent to the Virtual POS with the transaction. In this case, product information is displayed in transaction details and product report pages.Information about the product sold during the purchase can be sent to the Virtual POS with the transaction. In this case, product information is displayed in transaction details and product report pages.
It is a structure that allows some special information to be received during the transaction to appear on virtual pos screens and documents received from virtual mail.
The 1st special field among the special fields is sent to Garanti Bank. This field is shown in the reports received by the bank.
With the change made in the workplace definitions, it can be ensured that the values sent in this field appear in the card in-period transactions and card statements in the workplace name field.
For the use of custom fields, the workplace admin user must activate the custom fields to be used from the custom field definitions. Custom fields sent without being activated will cause an error. If you want the special field number 1 to go to the bank side, the phrase "appear on the bank side" should be checked.
In order for the custom fields to appear on the listing screens, they must be selected by the user from the custom field selection page. The selected custom fields appear as a column on the right side of the listing pages.
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.
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 with successful verification, "I did not do it" claims are terminated by the bank.
For Virtual POS Sales transactions, it is possible to proceed with 2 different methods by the merchant. If the merchant wishes, they can make all the improvements in the test environment. Alternatively, necessary improvements can be made for these transactions directly in the broadcast environment.
According to the method to be selected 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 |
StoreKey | 12345678 |
In the studies to be carried out in the test environment "https://sanalposprovtest.garantibbva.com.tr/servlet/gt3dengine" url 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 |
Parola | Destek.1 |
Password | 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) passwords) Sanal POS İlk Adımlar 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.garanti.com.tr/servlet/gt3dengine" url will be used.
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:
The form structure in html format below contains both common and differentiated tags for all 3D transaction types under Virtual POS Sales.
The changes that need to be made on this common structure are explained in detail in the relevant description page for the transaction type.
On the common html structure given above; the form structure required for the transaction type can be obtained by providing the following operations:
Delete the entire code block starting with the description "Additional Parameters can be added to this field" and ending with the description "Additional Parameters can be added to this field".
The transaction type expressed as "sales" in the line specified as follows in the code block indicates the Advance transaction type. This field should be kept as it is:
Specific to this transaction type; the following code block should be added to the form structure:
If the transaction is successful, the merchant writes the page url where the parameters of the successful transaction return will be met in the following code block:
In case the transaction fails, the merchant writes the page url where the parameters of the successful transaction return will be met in the following code block:
After the addition and subtraction operations specific to the transaction type mentioned above, the form block is ready and placed in the relevant html page.
After the form is filled and submitted by the visitors, the transaction continues on the Garanti BBVA Sales page.
After the transaction is completed on the sales page, the system will post a form to the address specified in the previous steps (Successful transaction url or failed transaction url)
In the page at the relevant address, this form data coming from the system must be parse as described here.
In the table below; there are descriptions of the data coming from the system. The data obtained after the parse process should be interpreted according to this table:
Domain Name | Description |
---|---|
mdstatus | Field where the 3D answer is given numerically |
mderrormessage | Textual description of the 3D response transaction status |
errmsg | 3D response error message in case of incorrect transactions |
clientid | Terminal id information of the merchant |
oid | Order number sent during the transaction |
response | Field indicating whether the operation was successful or not |
procreturncode | Provision response |
successurl | The url information to be returned in case of a successful transaction |
txninstallmentcount | Number of installments sent during the transaction |
refreshtime | Renewal time sent when processing |
orderid | Order number sent during the transaction |
cardholdername | Customer name sent during the transaction |
txntype | Transaction type specified during the transaction |
terminalmerchantid | Merchant number during the transaction |
txnamount | Total amount information sent during the transaction |
txntimestamp | Process time |
terminaluserid | Merchant username |
mode | Processed media information |
txncurrencycode | The currency specified at the time of the transaction |
secure3dhash | The hash information calculated during the transaction |
apiversion | API version information sent during the transaction |
companyname | Merchant name |
errorurl | The url information where the erroneous transactions sent during the transaction will be returned |
secure3dsecuritylevel | 3D model information specified during the transaction |
customeremailaddress | Customer email information sent during the transaction |
customeripaddress | Customer IP address information sent during the transaction |
terminalid | Terminal number |
terminalprovuserid | Provision user information sent during the transaction |
lang | Service response language preference information sent during the process |
hash | The hash data generated after the operation |
hashparams | Hash formula information to be used after the transaction |
hashparamsval | Hash details to be used after the operation |
Important Reminder : Before checking the provision results in the transaction returns after the installation;
You need to make sure that the returned data comes from the bank. There are several methods to do this. The hash value in the returned values must be the same as the hash value to be created by creating from the returned values, (hashparams value should be calculated from the returned values and hashparamsval should not be used. )Continuing the process according to the result of the query by querying with xml using the orderinq transaction type after each transaction,Checking each order from the virtual pos management screens before shipping,The amount value posted from the site to the virtual pos should be used instead of the amount that the customer sees on the site or the basket amount on the previous page, the amount to be withdrawn from the database should be used,You can check the original transaction amount with the amount returned as a result of the transaction, You can switch to the encrypted response structure, In this structure, the amount will not be changed because the amount will come in encrypted fields. The user can check the transaction amount returned in the answer and the amount in the transaction and catch whether there is any tampering in the transaction more securely in this way. The company can check the transaction status after the query by using the orderinq or orderhisinq functions after the sale and compare the incoming amount with the basket amount.
The return should only be checked for 00. There is no need for other cases and no calculation can be made.
• Expected order number?
• Request.Form.Get("procreturncode") is 00?
• Request.Form.Get("hashparams"); should not be null or ""
After the above checks, if the result is successful, the transaction should be confirmed.
'hashparams' => 'clientid:oid:authcode:procreturncode:response:mdstatus:cavv:eci:md:rnd:',r.
Hashparams are created sequentially as above. It is then encrypted with Cryptography sha1 by adding 3d Key at the end. If the result and Request.Form.Get("hash"); are the same, the result is successful. Otherwise the process should be checked.
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.
Error codes from this page you can reach.
List of test cards from this page you can reach.
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