-
Sanal Pos
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
This document describes the steps required for member merchants to be able to perform non 3Ds Inquiry 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 Inquiry Transactions
The sub-transaction types under the Virtual POS Inquiry transactions are generally as follows:
- Bonus Inquiry: This is the transaction type used to retrieve the bonus information on the card. The last two digits of the bonus amount returned in the reply message will be considered as kuruş. Bonus inquiry can only be made for Garanti cards and cards under the Bonus brand.
- Order Inquiry: It is the type of request that receives information about a specific transaction.
- Order Detail Inquiry: This is the transaction type in which the transactions of a specific order are queried.
- Date Range Inquiry: This is the transaction type that shows the details of the transactions between the two dates entered.
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:
Yapılacak çalışmaların test ortamında yürütülmesi durumunda, aşağıda belirtilen ön tanımlı değerler oldugu gibi kullanılabilir:
| Parametre | Değer |
|---|---|
| MerchantID | 7000679 |
| ProvUserID | PROVAUT / PROVRFN / PROVOOS |
| ProvisionPassword | 123qweASD/ |
| TerminalID | 30691297 |
| StoreKey | 12345678 |
Test ortamında yapılacak çalışmalarda "https://sanalposprovtest.garanti.com.tr/VPServlet" url'i kullanılacaktır.
Test ortamında yapılan işlemlerin takip edilebileceği ve görüntülenebileceği panele bu adresten erişebilirsiniz.
| Değişken | Değer |
|---|---|
| Kullanıcı Adı | 99999999999 |
| Parola | Destek.3 |
| Şifre | 147852 |
Not: Parola işlemlerinde hata alınması durumunda 2.kez deneme yapılmadan önce lütfen Bize Soru Gönderin formu ile bilgi veriniz.
Test ortamında kullanılabilecek tüm test kartlarının listesine bu sayfadan ulaşabilirsiniz.
Bu yöntem ile ilerlendiğinde, üye işyeri tarafından ilk adım olarak kurulumda kullanılacak olan şifreler (“PROVAUT”,“PROVOOS”, “PROVRFN” ve “3D” (storekey) şifreleri) Sanal POS İlk Adımlar dokümanı içerisinde belirtildiği şekilde sanal pos yönetim panelinden oluşturmalıdır.
Sonraki adımlarda, bu şekilde oluşturulan şifre ve hesaplar kullanılacaktır.
PROD ortamında yapılacak çalışmalarda "https://sanalposprov.garanti.com.tr/VPServlet" url'i kullanılacaktır.
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:
public static string Sha1(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA1CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string Sha512(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA512CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string GetHashData(string userPassword, string terminalId, string orderId, string cardNumber, ulong amount, int currencyCode) {\n var hashedPassword = Sha1(userPassword + terminalId);\n return Sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword).ToUpper();\n}
Public Shared Function Sha1(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA1CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function Sha512(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA512CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function GetHashData(ByVal userPassword As String, ByVal terminalId As String, ByVal orderId As String, ByVal cardNumber As String, ByVal amount As ULong, ByVal currencyCode As Integer) As String\n Dim hashedPassword = Sha1(userPassword & terminalId)\n Return Sha512(orderId & terminalId & cardNumber & amount & currencyCode & hashedPassword).ToUpper()\nEnd Function
public static String calculateHash(String data, String algorithm, String charset) throws UnsupportedEncodingException, NoSuchAlgorithmException {\n\tMessageDigest md = MessageDigest.getInstance(algorithm);\n\tbyte[] databytes = data.getBytes(charset);\n\t\n\tmd.update(databytes);\n byte[] hashBytes = md.digest();\n \n return byteArray2HexaDecimal(hashBytes);\n}\n\npublic static String sha1(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-1\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String sha512(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-512\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String getHashData(String userPassword, String terminalId, String orderId, String cardNumber, Long amount, int currencyCode) {\n var hashedPassword = sha1(userPassword + terminalId);\n return sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword);\n}
private function GenerateSecurityData($terminalId)\n {\n $password = \"password\";\n\n $data = [\n $password,\n str_pad((int)$terminalId, 9, 0, STR_PAD_LEFT)\n ];\n\n $shaData = sha1(implode('', $data));\n\n return strtoupper($shaData);\n }\n\n public function GenerateHashData()\n {\n $orderId = \"order_id\"; //must be uniqe\n $terminalId = \"terminal_id\"; //must be integer\n $cardNumber = \"1234123412341234\"; //card number\n $amount = \"100\"; //amount\n $currencyCode = \"currency_code\"; //must be int\n\n $hashedPassword = GenerateSecurityData($terminalId);\n\n $data = [\n $orderId, $terminalId, $cardNumber, $amount, $currencyCode, $hashedPassword\n ];\n \n $shaData = strtoupper(hash(\"sha512\", implode('', $data)));\n\n return strtoupper($shaData);\n }
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:
public static string Sha1(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA1CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string Sha512(string text) {\n var provider = CodePagesEncodingProvider.Instance;\n Encoding.RegisterProvider(provider);\n\n var cryptoServiceProvider = new SHA512CryptoServiceProvider();\n var inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text));\n\n var builder = new StringBuilder();\n for (int i = 0; i < inputbytes.Length; i++) {\n builder.Append(string.Format(\"{0,2:x}\", inputbytes[i]).Replace(\" \", \"0\"));\n }\n\n return builder.ToString().ToUpper();\n}\n\npublic static string GetHashData(string userPassword, string terminalId, string orderId, string cardNumber, ulong amount, int currencyCode) {\n var hashedPassword = Sha1(userPassword + \"0\" + terminalId);\n return Sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword).ToUpper();\n}
Public Shared Function Sha1(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA1CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function Sha512(ByVal text As String) As String\n Dim provider = CodePagesEncodingProvider.Instance\n Encoding.RegisterProvider(provider)\n Dim cryptoServiceProvider = New SHA512CryptoServiceProvider()\n Dim inputbytes = cryptoServiceProvider.ComputeHash(Encoding.GetEncoding(\"ISO-8859-9\").GetBytes(text))\n Dim builder = New StringBuilder()\n\n For i As Integer = 0 To inputbytes.Length - 1\n builder.Append(String.Format(\"{0,2:x}\", inputbytes(i)).Replace(\" \", \"0\"))\n Next\n\n Return builder.ToString().ToUpper()\nEnd Function\n\nPublic Shared Function GetHashData(ByVal userPassword As String, ByVal terminalId As String, ByVal orderId As String, ByVal cardNumber As String, ByVal amount As ULong, ByVal currencyCode As Integer) As String\n Dim hashedPassword = Sha1(userPassword & \"0\" & terminalId)\n Return Sha512(orderId & terminalId & cardNumber & amount & currencyCode & hashedPassword).ToUpper()\nEnd Function
public static String calculateHash(String data, String algorithm, String charset) throws UnsupportedEncodingException, NoSuchAlgorithmException {\n\tMessageDigest md = MessageDigest.getInstance(algorithm);\n\tbyte[] databytes = data.getBytes(charset);\n\t\n\tmd.update(databytes);\n byte[] hashBytes = md.digest();\n \n return byteArray2HexaDecimal(hashBytes);\n}\n\npublic static String sha1(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-1\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String sha512(String data) throws UnsupportedEncodingException, NoSuchAlgorithmException { \n return calculateHash(data, \"SHA-512\", \"ISO-8859-9\").toUpperCase();\n}\n\npublic static String getHashData(String userPassword, String terminalId, String orderId, String cardNumber, Long amount, int currencyCode) {\n var hashedPassword = sha1(userPassword + \"0\" + terminalId);\n return sha512(orderId + terminalId + cardNumber + amount + currencyCode + hashedPassword);\n}
private function GenerateSecurityData($terminalId)\n {\n $password = \"password\";\n\n $data = [\n $password,\n str_pad((int)$terminalId, 9, 0, STR_PAD_LEFT)\n ];\n\n $shaData = sha1(implode('', $data));\n\n return strtoupper($shaData);\n }\n\n public function GenerateHashData()\n {\n $orderId = \"order_id\"; //must be uniqe\n $terminalId = \"terminal_id\"; //must be integer\n $cardNumber = \"1234123412341234\"; //card number\n $amount = \"100\"; //amount\n $currencyCode = \"currency_code\"; //must be int\n\n $hashedPassword = GenerateSecurityData($terminalId);\n\n $data = [\n $orderId, $terminalId, $cardNumber, $amount, $currencyCode, $hashedPassword\n ];\n \n $shaData = strtoupper(hash(\"sha512\", implode('', $data)));\n\n return strtoupper($shaData);\n }
Request Structure
The request structure required for Virtual POS Bonus Inquiry 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:
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<GVPSRequest>\n\t<Mode>PROD</Mode>\n\t<Version>v0.01</Version>\n\t<ChannelCode></ChannelCode>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\n\t\t<HashData>B61DE1576B795C2CD1BC20AA6AB5D54E4A7D0102</HashData>\n\t\t<UserID>DENEME</UserID>\n\t\t<ID>30691297</ID>\n\t\t<MerchantID>7000679</MerchantID>\n\t</Terminal>\n\t<Customer>\n\t\t<IPAddress>127.0.0.1</IPAddress>\n\t\t<EmailAddress>eticaret@garanti.com.tr</EmailAddress>\n\t</Customer>\n\t<Card>\n\t\t<Number>4282209027132016</Number>\n\t\t<ExpireDate>0518</ExpireDate>\n\t\t<CVV2>358</CVV2>\n\t</Card>\n\t<Order>\n\t\t<OrderID>GARANTI_TEST_003</OrderID>\n\t\t<GroupID></GroupID>\n\t</Order>\n\t<Transaction>\n\t\t<Type>rewardinq</Type>\n\t\t<InstallmentCnt></InstallmentCnt>\n\t\t<Amount>100</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 | This is the field where the process mode is written | |
| <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 | Alphanumeric | 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></Type>\n\t<Amount></Amount>\n\t<CurrencyCode></CurrencyCode>\n\t<CardholderPresentCode></CardholderPresentCode>\n\t<MotoInd></MotoInd>\n</Transaction>\n
| 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. |
| <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. If the transaction is a "Partial Refund" transaction, the amount entered in this field is refunded. |
| <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 Bonus Inquiry transactions, the response structure returned from the service after the request sent in the previous headings is generally 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:
<GVPSResponse>\n\t<Mode></Mode>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\n\t\t<UserID>DENEME</UserID>\n\t\t<ID>30691297</ID>\n\t\t<MerchantID>7000679</MerchantID>\n\t</Terminal>\n\t<Customer>\n\t\t<IPAddress>127.0.0.1</IPAddress>\n\t\t<EmailAddress>eticaret@garanti.com.tr</EmailAddress>\n\t</Customer>\n\t<Order>\n\t\t<OrderID>GARANTI_TEST_003</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>708314662161</RetrefNum>\n\t\t<AuthCode></AuthCode>\n\t\t<BatchNum>001684</BatchNum>\n\t\t<SequenceNum>026087</SequenceNum>\n\t\t<ProvDate>20170324 15:28:37</ProvDate>\n\t\t<CardNumberMasked>428220******2016</CardNumberMasked>\n\t\t<CardHolderName></CardHolderName>\n\t\t<CardType>FLEXI</CardType>\n\t\t<HashData>777220D60D0B37F5F93E52340BAACC76871420A1</HashData>\n\t\t<HostMsgList></HostMsgList>\n\t\t<RewardInqResult>\n\t\t\t<RewardList>\n\t\t\t\t<Reward>\n\t\t\t\t\t<Type>FBB</Type>\n\t\t\t\t\t<TotalAmount>75200</TotalAmount>\n\t\t\t\t\t<LastTxnGainAmount>0</LastTxnGainAmount>\n\t\t\t\t</Reward>\n\t\t\t\t<Reward>\n\t\t\t\t\t<Type>BNS</Type>\n\t\t\t\t\t<TotalAmount>6071</TotalAmount>\n\t\t\t\t\t<LastTxnGainAmount>0</LastTxnGainAmount>\n\t\t\t\t</Reward>\n\t\t\t</RewardList>\n\t\t\t<MilRewardInqResult>\n\t\t\t\t<Reward>\n\t\t\t\t\t<Type>MIL</Type>\n\t\t\t\t\t<MilAmount>28226</MilAmount>\n\t\t\t\t\t<MilValue>35283</MilValue>\n\t\t\t\t\t<UseRate>80</UseRate>\n\t\t\t\t</Reward>\n\t\t\t</MilRewardInqResult>\n\t\t\t<ChequeList>\n\t\t\t\t<Cheque>\n\t\t\t\t\t<Type>P</Type>\n\t\t\t\t\t<Amount>2000</Amount>\n\t\t\t\t\t<Count>51</Count>\n\t\t\t\t\t<ExpireDate>20221224</ExpireDate>\n\t\t\t\t\t<UsageRate>0000</UsageRate>\n\t\t\t\t\t<MinTxnAmount>0</MinTxnAmount>\n\t\t\t\t\t<ID>0000036605</ID>\n\t\t\t\t\t<Bitmap>0000</Bitmap>\n\t\t\t\t\t<Description></Description>\n\t\t\t\t</Cheque>\n\t\t\t</ChequeList>\n\t\t</RewardInqResult>\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 Labels | Data Writing Format | Description and notes |
|---|---|---|
| <Mode> | PROD - TEST | This is the field where the process mode is written |
| <Terminal> | This tag contains sub tags within itself. The sub tags it contains are given in the headings below. | |
| <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. |
<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.
<Terminal>\n\t<ProvUserID></ProvUserID>\n\t<UserID></UserID>\n\t<ID></ID>\n\t<MerchantID></MerchantID>\n</Terminal>
Bu etiket içerisinde yer alan alt etiketler ve detayları aşağıda verilmiştir:
| Bottom Label | Maks 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 |
| <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 the customer information sent in the request is returned in the same way in the response.
<Customer>\n\t<IPAddress></IPAddress>\n\t<EmailAddress></EmailAddress>\n</Customer>
| Bottom Label | Maks 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. |
<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
<Transaction>\n <Response></Response>\n <RetrefNum></RetrefNum>\n <AuthCode></AuthCode>\n <BatchNum></BatchNum>\n <SequenceNum></SequenceNum>\n <ProvDate></ProvDate>\n <CardNumberMasked></CardNumberMasked>\n <CardHolderName></CardHolderName>\n <CardType></CardType>\n <HashData></HashData>\n <HostMsgList></HostMsgList>\n <RewardInqResult></RewardInqResult>\n <CampaignChooseLink></CampaignChooseLink>\n <GarantiCardInd></GarantiCardInd>\n</Transaction>
| 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 | The transaction number generated by Virtualpos is returned |
| <AuthCode> | Nümerik | This is the field where the confirmation code is returned. |
| <BatchNum> | This is the field that returns which batche the transactions will enter. | |
| <SequenceNum> | This is the field where the name of the cardholder is sent. | |
| <ProvDate> | YYYYMMDD | This is the field where the provision date is returned. |
| <CardNumberMasked> | This is the field where the first 6 and last 4 digits of the card number and the fields in between are returned with *. | |
| <CardHolderName> | This is the field where the name of the cardholder is sent. | |
| <CardType> | This is the field where the type of card processed is returned. | |
| <HashData> | This 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> | ||
| <CampaignChooseLink> |
<Response> Alt Tags and Descriptions
<Response>\n <Source></Source>\n <Code></Code>\n <ReasonCode></ReasonCode>\n <Message></Message>\n <ErrorMsg></ErrorMsg>\n <SysErrMsg></SysErrMsg>\n</Response>
| Alt Tags | Description and notes |
|---|---|
| <Source> | This is the field where the source information is returned. |
| <Code> | This is the field where Approved - declined information is returned. |
| <ReasonCode> | This is the field where the answer code is returned. |
| <Message> | This is the field where the message information is returned. |
| <ErrorMsg> | This is the field where the error message is returned. |
| <SysErrMsg> | This is the field where the system error message is returned. |
<RewardInqResult> Tag, Subtags and Descriptions
| Bottom Tags | Data Writing Format | Description and notes |
|---|---|---|
| <RewardList> | This tag contains sub tags. Details about the sub-tags are given in the headings below. | |
| <ChequeList> | This tag contains sub tags. Details about the sub-tags are given in the headings below. |
<RewardList> Tag and Descriptions
| Bottom Tags | Data Writing Format | Description and notes |
|---|---|---|
| <Reward> | This tag contains sub tags. Details about the sub-tags are given in the headings below. |
<Reward> Tag and Descriptions
| Bottom Label | Data Writing Format | Description and notes |
|---|---|---|
| <Type> | Alphanumeric | This is the field where the reward type is returned. The values that can come in this field and their meanings are as follows:BNS: Bonus PointsFBB: Company Based Bonus Points |
| <TotalAmount> | 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 award amount is returned. |
| <LastTxnGainAmount> | 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 last won prize amount is returned. |
<MilRewardInqResult> Tag, Subtags and Descriptions
| Bottom Labels | Data Writing Format | Description and notes |
|---|---|---|
| <Reward> | This tag contains sub tags. Details about the sub-tags are given in the headings below. |
<Reward> Tag and Bottom Tags
| Bottom Labels | Data Writing Format | Description and notes |
|---|---|---|
| <Type> | ||
| <MilAmount> | ||
| <MilValue> | ||
| <UseRate> |
<ChequeList> Tag and Explanations
| Bottom Tags | Data Writing Format | Description and notes |
|---|---|---|
| <Cheque> | This tag contains sub tags. Details about the sub-tags are given in the headings below. |
<Cheque>Tag and Descriptions
| Bottom Tags | Data Writing Format | Description and notes |
|---|---|---|
| <Type> | Alfanümerik | The field where the check type is returned. |
| <Count> | The field where the number of checks is returned. | |
| <ExpireDate> | Check expiration date is returned. | |
| <Amount> | The numeric is sent as LLLLLLKK. The last 2 digits represent cents. 1,00 TL -> 100 11,22 TL->1122 0,01TL -> 1 | Check amount is returned. |
| <UsageRate> | Check utilization rate is returned. | |
| <MinTxnAmount> | Nümerik LLLLKK şeklinde yollanır. Son 2 hane kuruşu ifade eder. 1,00 TL -> 100 11,22 TL->1122 0,01TL -> 1 şeklinde | It is the field where the minimum transaction amount required for check usage is returned. |
| <ID> | It is the field where the Campaign ID information is returned. | |
| <Bitmap> | It is the field where the Bitmap ID produced by the bank is returned. |
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.
