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.

Sanal POS İşlemleri Genel Kavramlar 

Garanti Sanal POS, internet üzerinden yapılan satışlarda kredi kartı ile ödeme alınabilmesi için oluşturulan güvenli bir ödeme çözümüdür.

Üye işyerleri, mağazalarında internet üzerinde bir şube açıp, Garanti Sanal POS ile, onu hiç kapanmayan bir satış platformu haline gelebilir. Böylece hem müşteri sayıları, hem de cironun artırılmasına katkı sağlanır.

Garanti Sanal POS altında genel olarak aşağıdaki işlemler gerçekleştirilmektedir:

• Satış İşlemleri
• Ortak Ödeme Sayfası İşlemleri
• İptal İşlemleri
• İade İşlemleri
• Kapama İşlemleri
• Sorgulama İşlemleri

Bu doküman içerisinde, üye işyerlerinin Garanti Sanal POS altında 3D’li Peşin Satış işlemlerinin sağlanabilmesi için gerekli olan adımlar, her bir adım içerisinde yapılması gereken işlemler ve gönderilen işlem istekleri ve alınan cevap mesajlarının yapıları anlatılmaktadır. 

Sanal POS İptal İşlemleri

İptal, yapılan bir işlemin gün içerisinde geçersiz olması için yapılan işlemdir.

İşlemler aynı gün içerisinde iptal edilebilir. Takip eden günler için işlemin iptal edilmesi gerekiyorsa yapılması gereken işlem iadedir.

İptal işleminin iptali yoktur. Bu sebeple yanlışlıkla bir iptal yapılırsa bu durumda ipal edilen işlemin tekrar yaptırılması gerekmektedir.

İptal işlemleri kart üzerinden iz oluşturmaz. Kart ekstrelerinde ya da dönemi içi işlemlerde gözükmez.

3D Kavramı

3D Secure , PoS üzerinde kart sahiplerinin şifre ile doğrulandığı uygulamanın, SanalPoS üzerinde yapılan halidir. Kart sahibi, işlemde şifre kullanması için kart bankasına ait doğrulama ekranlarına yönlendirilir. Kart sahibi bu ekranlar üzerinden bankasının istediği bilgileri girerek, gerçekten kullanılan kartın kendisine ait bir kart olduğunu gösterir.

Doğrulama sonucunda, doğrulama durumu işyeri bankaya (işyerine) döndürülür. Daha sonra 3D bilgilerinin durumuna göre provizyon işleminin gerçekleştirilmesi ya da işlemin sonlandırılması gerçekleştirilir.

3D Secure Master, Visa ve American Express(Amex) kartların desteklediği bir uygulamadır. 3D model (aşağıda işyeri modelleri hakkında bilgi verilmektedir) kullanan işyerlerinin Mastercard, Visa ve Amex dışındaki kartlar için 3D doğrulaması gerçekleştirmeden direk provizyona gelmeleri gerekmektedir. 3D secure desteklenmediği için bu tür işlemlerde Fraud sorumluluğu işyerine aittir. İşyeri kendisini koruyacak önlemleri almalıdır.  

Sanal POS 3D'siz İşlemler

Gerçekleşen işlemin provizyon akışı sırasında herhangi bir 3D secure aşamasına değmeden sonuçlanmasıdır. Bu işlem tipinde müşterinin “ben yapmadım” itirazları chargeback talebine dönüşür. İşyerinden işlemin müşteri tarafından yapıldığına yönelik kanıtlar talep edilerek chargeback süreci değerlendirilir. 3D’li işlemlerde başarılı doğrulaması yapılan işlemlerde işlemi “ben yapmadım” talepleri banka tarafında sonlandırılır.

Test / Prod Ortam Seçimleri: 

Sanal POS Satış işlemleri için, üye işyeri tarafından 2 farklı yöntem ile ilerlenmesi mümkündür. Üye işyeri dilerse yapacağı tüm geliştirmeleri Test ortamında yapabilir. Alternatif olarak doğrudan yayın ortamında da bu işlemler için gerekli geliştirmeler yapılabilir.

Üye işyeri tarafından seçilecek yönteme göre, Sanal POS satış işlemlerine başlamadan önce aşağıdaki başlıklardan uygun olana göre ilk işlemlerin yapılması gerekmektedir:

Hash Algoritması

Bu doküman içerisinde, birçok işlem tipi altında kullanılan ve istek mesajı içerisinde <HashData> şeklinde yer alan etiket için gerekli olan verinin nasıl oluşturulacağını adım adım anlatılmaktadır.

İstek mesajları içerisinde yer alan <HashData> etiketi; kullanıcıya ait şifre doğrulamasının yapılmasını sağlayan alandır. Hash oluşturma detayları aşağıda ayrıca anlatılmaktadır.

Yeni SanalPoS uygulamasında, terminale ait şifrenin açık şekilde dolaşmasının engellenmesi için HASH yapısı kullanılmaktadır.

Hash hesabı:

• Hashedpassword bilgisinin hesaplanmasında SHA1
• Hashvalue değerinin hesaplanmasında SHA512 algoritması kullanılmaktadır.

Hash hesaplamasında, İki parçalı HASH yapısı kullanılmaktadır. İlk aşamada provizyon şifresinin, terminal numarası ile yanyana getirilmesi ile SHA1 algoritması kullanılarak hashedpassword değerinin elde edilmesi sağlanacaktır.

Hash oluşturmak için gerekli olan işlemler, aşağıda farklı programlama dilleri için sunulmuştur:

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 Variable Amount Repeat Sales transactions without Virtual POS 3D 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

<Recurring> Tag and Details

This is the field where repetitive transaction information is sent. The label structure is as follows:

<PaymentList> Tag and Details

This is the field where due dates and amounts are sent.

<Payment> Tag and Details

This is the field where due dates and amounts are sent.

<Transaction> Tag and its Rules

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

Response Structure

For Fixed Amount Repeat Sales transactions without Virtual POS 3D, the response structure returned from the service after the request sent in the previous topics 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 repeat 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:

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

Bu etiket içerisinde yer alan alt etiketler ve detayları aşağıda verilmiştir:

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

<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

<HostMsgList> Tag, Subtags and Descriptions

<RewardInqResult> Tag, Subtags and Descriptions

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.