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 Procedures
• Refund Procedures
• Closing Operations
• Inquiry Procedures

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.

Virtual POS Additional Area Transactions

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.

1. Address Sending:

Address information can be sent to VirtualPoS during the transaction. The information sent is displayed on the order detail pages for information purposes.

2. Product Information Submission:

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.

3. Custom Field Submission:

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 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 with successful verification, "I did not do it" claims are terminated by the bank.

Test / Prod Environment Selections:

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:

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:

Virtual POS Sales General Form Structure for All Transaction Types with 3D

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.

Virtual POS Sales 3D Additional Fields Product Information Submission Process Specific Form Structure Edits

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:

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:

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. 

Sales Page Transaction Reply

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:

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.

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.