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

In this document, the steps required for member merchants to be able to provide non 3Ds Sales 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 Sales Transactions

The sub transaction types under Virtual POS Sales transactions are generally as follows:

• Installment Sales: It is the transaction type that enables installment transactions.

• Pre-Authorization: Preauth - Preauthorization process ensures that the amount to be taken from the card is blocked between 7 and 9 days by blocking an amount on the card. In this way, it is guaranteed that the card will not receive a limit error when the authorization is closed. During this period, pre-authorization closing process must be performed in order for the amount to be recognized. At the end of the pre-authorization blocking period, the amount block on the card is removed. In the pre-authorization closing requests sent after the end of this period, the transaction result is returned according to whether the card has a limit or not.

• Point Sale: It is the transaction type that allows you to make a purchase with bonus. Total transaction amount is sent in the Amount field. In UsedAmount field, the bonus rate to be used is sent. Debit is passed to the card side as much as amount - usedbonus amount. Used bonus is deducted from card bonuses. Bonus utilization is reflected in the workplace accounting the next day regardless of the workplace working conditions.

• Repeat Sales: The sales transaction is realized at regular intervals and goes to provisioning.

• DCC: DCC (dynamic currency conversion) is a system that ensures that the amount to be reflected on the card side in transactions made to foreign bank cards is made at the exchange rate of the card. In this system, the transaction amount is reflected to the merchant side in TL. The card side is reflected with the selected exchange rate. In this way, the cardholder clearly knows the amount to be reflected on the statement. For this transaction, the merchant and the bank side earn commission. Before the DCC transaction, DCC query is performed to obtain the supported exchange rates and exchange rate values. These values are reflected on the screen and the customer is asked to select one of the TL or incoming exchange rate values. The transaction is realized at the selected exchange rate.

• Multi Currency: Transactions in foreign currencies other than Turkish lira.

• Common Card: The Common Card is a card payment system that regulates the cash and document flow that occurs in the sales made by companies to their customers and allows term shopping.
• Term Sale: Receipt of the sales price on a specified date.

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:

Request Structure

The request structure required for Virtual POS non 3Ds Advance Sales 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:

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.

<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.

The sub-tags within this tag and their details are given below:

<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.

<Card> Label and Rules for the <Card> Label and the Label to be placed under it

This is the field where card information is sent. Credit card information is a mandatory field except for some transaction types.

Note: Unlike other credit cards, American Express cards consist of 15 digit numbers instead of 16, so your card information entry screens must be arranged to accept 15 digits. Unlike other credit cards, the CVV, i.e. security codes of American Express cards have 4 digits instead of 3 and are located on the front of the card. Your security code entry screens must be configured to accept 4-digit codes.

<Order> Label and Rules for the <Order> Label

This is the field where the information and details of the order are sent.

<Transaction> Tag and its Rules

This is the field where transaction information and financial information are sent.

Response Structure 

The response structure returned from the service after the request sent in the previous headings for Virtual POS Advance Sales transactions Non 3ds 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:

In the Virtual POS cash sales transaction, the response structure is generally as follows:

The tags in the answer structure given above and the sub tags under these tags are given in the heading below:

<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.

<Transaction> Tag Label and Rules of the <Transaction> Tag

<Response> Alt Tags and Descriptions

<PaymentList> and <Payment> Tags

The <PaymentList> tag contains the <Payment> tag.

The details of the <Payment> tag are given in the table below:

<HostMsgList> Tag, Subtags and Descriptions

<RewardInqResult> Tag, Subtags and Descriptions

<RewardList> Tag and Descriptions

<ChequeList> Tag and Explanations

Code Examples

Below are github repo links to virtual POS Advance Sales transaction examples written in different software languages. You can review the codes written with predefined values via 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.

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.

Frequently Asked Questions

<ErrorMsg>Kullanıcı şifresi hatalı</ErrorMsg>” hata mesajı aldığımızda ne yapmalıyız ?

<Response>

      <Source>GVPS</Source>

      <Code>92</Code>

      <ReasonCode>0651</ReasonCode>

      <Message>Declined</Message>

      <ErrorMsg>Kullanıcı şifresi hatalı</ErrorMsg>

      <SysErrMsg>ErrorId: 0651</SysErrMsg>

   </Response>

Alınan hata kodlamanızda gönderilen hash datayı değerini oluşturan alanların sistemde tanımlı olan yada kodlama post edilen değerlerle uyuşmadığını durumlarda alınmaktadır. Bu alanları kontrol ederek yeniden işlem denemenizi ve hatanın devamı halinde hash değerini oluşturan alanları ve oluşturduğunuz hash değerini tarafımıza göndermenizi rica ederiz.

Ayrıca kodlamada kullanılan PROVAUT ve 3D şifrenizi resetlemenizi ve kodlamada güncellemenizi rica ederiz.

<ErrorMsg>Terminal kaydı yok</ErrorMsg>” hata mesajı aldığımızda ne yapmalıyız?

<Response>

      <Source>GVPS</Source>

      <Code>92</Code>

      <ReasonCode>0752</ReasonCode>

      <Message>Declined</Message>

      <ErrorMsg>Terminal kaydı yok</ErrorMsg>

      <SysErrMsg>ErrorId: 0752</SysErrMsg>

    </Response>

“ErrorId: 0752”   İşlemde kullandığınız Terminal numarasını ve post adresinizi kontrol etmelisiniz.

PROD Provizyon post adresi 3D'siz için tıklayınız.