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

Request Structure

The request structure required for Virtual POS Multi-Currency 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:

<?xml version=\"1.0\" encoding=\"iso-8859-9\"?>\n<GVPSRequest>\n<Mode>TEST</Mode>\n\t<Version>512</Version>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\n\t\t<HashData>D7779FDADE4FD3124B66B12F6F7BA34CFBE2FBBED6F06D7D667A52A2B499FE01438AFCAC753F566AFAF7EAAFA10053061F712B7F111F76E964D18BBAE18A6ACA</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>5406697543211173</Number>\n\t\t<ExpireDate>0323</ExpireDate>\n\t\t<CVV2>465</CVV2>\n\t</Card>\n\t<Order>\n\t\t<OrderID>fa18e7e829694365818ff7672292d608</OrderID>\n\t\t<GroupID />\n\t</Order>\n\t<Transaction>\n\t\t<Type>sales</Type>\n\t\t<Amount>10000</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 İşlem modunun yazıldığı alandır 
<Version> 16 byte No format requirement 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.
<ChannelCode>  1 byte  Alfanümerik Channel information will be sent. It must be empty.
<Terminal>  This tag contains sub tags. The tags it contains and their rules are given in the following headings.
<Customer>  This tag contains sub tags. The tags it contains and their rules are given in the following headings.
<Card>  This tag contains sub tags. The tags it contains and their rules are given in the following headings.
<Order>  This tag contains sub tags. The tags it contains and their rules are given in the following headings.
<Transaction>  This tag contains sub tags. The tags it contains and their rules 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.

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

<Card>\n\t<Number></Number>\n\t<ExpireDate></ExpireDate>\n\t<CVV2></CVV2>\n</Card>
Bottom Label Max Size  Data Writing Format Data Writing Format Description and notes
<Number> Min: 15 - Max : 19 Nümeric This is the field where the card number is sent.
<ExpireDate> 4 byte MMYY (Last 2 digits of Month and Year) This is the field where the expiration date of the card is sent.
<CVV2> Min : 3 Max : 4 (Amex) Nümeric This is the field where CVV information of the card is sent.

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

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

<Order>\n\t<OrderID></OrderID>\n\t<GroupID />\n</Order>
Bottom Label Max Size Data Writing Format Description and notes
<OrderID> 36 byte No format requirement This is the field where the Order Number is sent. Order based must be unique. It must be generated by companies
<GroupID> 36 byte No format requirement It is the field used to categorize (group) orders. For example: Orders sent with campaigns can be separated with an information written in GroupID.

<Transaction> Tag and its Rules

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

<Transaction>\n\t<Type>sales</Type>\n <InstallmentCnt>3</InstallmentCnt>\n\t<Amount>10000</Amount>\n\t<CurrencyCode>949</CurrencyCode>\n\t<CardholderPresentCode>0</CardholderPresentCode>\n\t<MotoInd>N</MotoInd>\n</Transaction>
Bottom Label Max Size Data Writing Format Description and notes
<Type> 32 byte Alphanumeric 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.
<InstallmentCnt> 2 byte Numeric Enter the number of installments.
<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.
<CurrencyCode>  3 byte Numeric 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 Numeric Enter 0 for normal transactions and 13 for 3D transactions.
<MotoInd> 1 byte Alphanumeric It takes Y and N values. N is sent for Ecommerce transactions. Y is sent for transactions with Moto transaction status.
<InstallmentCnt> 2 byte Numeric Enter the number of installments.

 Response Structure 

For Virtual POS Multi-Currency Sales transactions Non 3ds, 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 Virtual POS multi-currency transactions, the response structure is generally as follows:

<GVPSResponse>\n\t<Mode></Mode>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\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<Order>\n\t\t<OrderID>fa18e7e829694365818ff7672292d608</OrderID>\n\t\t<GroupID></GroupID>\n\t</Order>\n\t<Transaction>\n\t\t<Response>\n\t\t\t<Source>HOST</Source>\n\t\t\t<Code>00</Code>\n\t\t\t<ReasonCode>00</ReasonCode>\n\t\t\t<Message>Approved</Message>\n\t\t\t<ErrorMsg></ErrorMsg>\n\t\t\t<SysErrMsg></SysErrMsg>\n\t\t</Response>\n\t\t<RetrefNum>208107225376</RetrefNum>\n\t\t<AuthCode>886867</AuthCode>\n\t\t<BatchNum>004537</BatchNum>\n\t\t<SequenceNum>005094</SequenceNum>\n\t\t<ProvDate>20220322 10:38:40</ProvDate>\n\t\t<CardNumberMasked>540669******1173</CardNumberMasked>\n\t\t<CardHolderName>4517******* 4517**********</CardHolderName>\n\t\t<CardType>BONUS</CardType>\n\t\t<HashData>01B6E1EA84AEE9CE3EE343718EC3AE0BC621B3DB1A04B6A48377D9904E0653CFA4D3FF87AAD4EA8BFE95219C8AEF0CA1A809ED03E418718A91750711619FEFF3</HashData>\n\t\t<HostMsgList>\n\t\t\t<HostMsg>TEST AAAAAAAAAAAAAAAAAAAAAAAAAAA</HostMsg>\n\t\t\t<HostMsg>TEST BBBBBBBBBBBBBBBBBBBBBBBBBBB</HostMsg>\n\t\t</HostMsgList>\n\t\t<RewardInqResult>\n\t\t\t<RewardList></RewardList>\n\t\t\t<ChequeList></ChequeList>\n\t\t</RewardInqResult>\n\t\t<CampaignChooseLink> https://sanalposprovtest.garantibbva.com.tr/servlet/campaignchoose?campaignKey=BC3CFF411EA971544525BB281172F2011C3C1CFB</CampaignChooseLink>\n\t\t<GarantiCardInd>Y</GarantiCardInd>\n\t</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
<Customer> This is the field where the customer information sent in the request structure is sent back for verification purposes.
<Order> This tag contains sub tags within itself. The sub tags it contains are given in the headings below.
<Transaction>  This tag contains sub tags within itself. The sub tags it contains are given in the headings 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.

<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

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 Returns the transaction number generated by Sanalpos
<AuthCode>  Nümerik This is the field where the approval code is returned.
<BatchNum>  It is the field where the batche in which the transactions will be entered is returned.
 <SequenceNum>  Transaction sequence number
<ProvDate>  YYYYMMDD Field where provision date is returned.
<CardNumberMasked> It is the field where the first 6 and last 4 digits of the card number and the fields in between are returned with *.
<CardHolderName> It is the field where the name of the cardholder is returned.
<CardType>  It is the field where the card type of the transaction is returned.
<HashData> It 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>

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. 

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.

Error Codes

Error codes from this page you can reach.

Test Cards

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