-
Sanal POS
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’siz 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 Satış İşlemleri
Sanal POS Satış işlemleri altında yer alan alt işlem tipleri genel olarak aşağıdaki şekildedir:
- Peşin: Peşin satın alma yapılmasını sağlayan işlem tipidir.
- Taksitli Satış: Taksitli işlem yapılmasını sağlayan işlem tipidir.
- Ön Otorizasyon: Preauth – Ön otorizasyon işlemi kart üzerinde bir tutar bloke konularak karttan alınacak tutarın 7 ile 9 gün arasında blokede tutulmasını sağlar. Bu şekilde provizyon kapaması yapıldığında kartın limit hatası almayacağı garantiye alınmış olur. Bu süre zarfından tutarın muhasebeleştirilmesi için ön oto kapama işleminin yapılması gerekmektedir. Ön otorizasyon bloke süresi sonunda kart üzerindeki tutar blokesi kaldırılır. Bu süre sona erdikten sonra gönderilen ön otorizasyon kapama isteklerinde kartın limitinin olup olmamasına göre işlem sonucu döner.
- Puanlı Satış: Bonus ile satın alma yapılmasını sağlayan işlem tipidir. Amount alanında toplam işlem tutarı yollanılır. UsedAmount alanında kullanılacak bonus oranı yollanılır. Kart tarafına amount – usedbonus tutarı kadar borç geçilir. Kullanılan bonus kart bonuslarından düşürülür. Bonus kullanımları işyeri çalışma koşullarından bağımsız olarak ertesi gün işyeri muhasebesine yansır.
- Tekrarlı Satış: Satış işleminin düzenlikli aralıklar ile gerçekleşip provizyona gitmesidir.
- DCC: DCC (dinamic currency convertion) yurt dışı banka kartlarına yapılan işlemlerde kart tarafına yansıyacak tutarın kartın kuru üzerinden yapılmasını sağlayan sistemdir. Bu sitemde işyeri tarafına işlem tutarı TL üzerinden yansır. Kart tarafına seçilen kur ile yansıma yapılır. Bu şekilde kart sahibi ekstresine yansıyacak tutarı net olarak bilir. Bu işlem için işyeri ve banka tarafı komisyon kazancı sağlar. DCC işlemi öncesinde DCC sorgulama işlemi yapılarak desteklenen kurların ve kur değerlerinin alınması sağlanır. Bu değerler ekrana yansıtılarak müşterinin TL veya gelen kur değerlerinden birisini seçmesi istenir. Seçilen kur üzerinden işlem gerçekleştirilir.
- Multi Currency: Türk lirası haricinde, yabancı para cinsinden işlem yapılabilmesidir.
- Ortak Kart: Ortak Kart, firmaların müşterilerine yapmış olduğu satışlarda oluşan, nakit ve belge akışını düzenleyen ve vadeli alışverişe imkan veren kartlı bir ödeme sistemidir.
- Vadeli Satış: Satış bedelinin belirlenmiş bir tarihte alınması işlemidir.
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.
İstek (Request) Yapısı
Sanal POS 3D’siz Taksitli Satış işlemleri için gerekli olan istek yapısı aşağıdaki tabloda belirtilmiştir. Tablo içerisinde ilk kolonda yer alan ana tag altında yer alanabilecek her tag için gerekli olan bilgi ve açıklamalar incelenmeli ve istek mesajı bu tabloda belirtilen kurallara göre sağlanmalıdır:
<?xml version=\"1.0\" encoding=\"iso-8859-9\"?>\n<GVPSRequest>\n\t<Mode>TEST</Mode>\n\t<Version>512</Version>\n\t<Terminal>\n\t\t<ProvUserID>PROVAUT</ProvUserID>\n\t\t<HashData>8BCADEC236F12240D610AE3F43581E901B5C8DC83BEB12ADACEEF7777509F0E490909973AB7181774D224D93EBEDEF11496F42CDC08DCC32753180923CF60438</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>1d899afe84e941f0bce40bb4edb3a30f</OrderID>\n\t\t<GroupID />\n\t</Order>\n\t<Transaction>\n\t\t<Type>sales</Type>\n\t\t<InstallmentCnt>3</InstallmentCnt>\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>
Bu yapı içerisinde birçok etiket kendi içerisinde alt etiketleri içermektedir. Her bir etiketin anlatıldığı ilgili başlık altında, alt etiketi olmayan etiketlerin kullanım kuralları ve alt etiketi olan etiketlerin de detayları ayrı başlık halinde verilerek sunulmaktadır.
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <Mode> | PROD | İşlem modunun yazıldığı alandır | |
| <Version> | 16 byte | Format zorunluluğu yok | Kullanılan Api versiyonunun yazıldığı alandır. Sha512 oalrak hash hesaplanması kapsamında bu alanda 512 değerinin gönderilmesi gereklidir. |
| <Terminal> | Bu etiket içerisinde alt etiketler yer alır. İçerdiği etiketler ve kuralları devam eden başlıklarda verilmiştir. | ||
| <Customer> | Bu etiket içerisinde alt etiketler yer alır. İçerdiği etiketler ve kuralları devam eden başlıklarda verilmiştir. | ||
| <Card> | Bu etiket içerisinde alt etiketler yer alır. İçerdiği etiketler ve kuralları devam eden başlıklarda verilmiştir. | ||
| <Order> | Bu etiket içerisinde alt etiketler yer alır. İçerdiği etiketler ve kuralları devam eden başlıklarda verilmiştir. | ||
| <Transaction> | Bu etiket içerisinde alt etiketler yer alır. İçerdiği etiketler ve kuralları devam eden başlıklarda verilmiştir. |
<Terminal> Etiketi ve Altında Yer Alacak Etiket ve Detayları
Sanal pos doğrulamasının sağlanması için sanal pos numarası kullanıcı bilgisi gibi parametreler yollanılır.
<Terminal>\n\t<ProvUserID></ProvUserID>\n\t<HashData></HashData>\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:
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <ProvUserID> | 32 byte | Format zorunluluğu yok | Terminale ait provizyon kullanıcı kodunun gönderildiği alandır. Burada Prov kullanıcısı, İptal iade kullanıcısı veya OOS kullanıcısı bulunabilir |
| <HashData> | 32 byte | Hash algoritması: SHA512 formatında olacaktır. Hash çevrimi sonrasında küçük harflerin büyük harfe çevrilmesi gerekmektedir. Detayları aşağıda yer almaktadır. | Kullanıcıya ait şifre doğrulamasının yapılmasını sağlanılan alandır. Hash oluşturma detayları bu doküman içerisinde ayrıca anlatılmaktadır. |
| <UserID> | Format zorunluluğu yok | İşlemi yapan kullanıcının (Agent - Satış Temsilcisi) yollandığı alandır. | |
| <ID> | 9 byte | Nümerik | Terminal numarasının yollandığı alandır |
| <MerchatID> | 9 byte | Nümerik | İşyeri numarasının yollandığı alandır. |
<Customer> Etiketi ve Altında Yer Alacak Etiket ve Kuralları
Müşteri Bilgilerinin yollanıldığı alandır. Tag içerisinde yer alan bilgilerin yollanılması zorunludur.
<Customer>\n <IPAddress></IPAddress>\n <EmailAddress></EmailAddress>\n</Customer>
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <IPAdress> | 20 byte | Format zorunluluğu yok | İşlemi yapan müşteriye ait IP adresinin yollanıldığı alandır. Fraud kontrollerinin sağlanabilmesi için zorunlu olarak yollanılması gerekmektedir. |
| <EmailAddress> | 64 byte | İşlemi yapan müşteriye ait E-Mail adresinin yollanıldığı alandır. |
<Card> Etiketi ve Altında Yer Alacak Etiket ve Kuralları
Kart bilgilerinin yollanıldığı alandır. Bazı işlem tipleri dışında kredi kartı bilgileri zorunlu alandır.
Not: American Express kartlar diğer kredi kartlarından farklı olarak 16 yerine 15 haneli numaralardan oluştuğundan, kart bilgisi giriş ekranlarınızın 15 haneyi de kabul edecek şekilde düzenlenmesi gerekmektedir. American Express kartların CVV, yani güvenlik kodları diğer kredi kartlarından farklı olarak 3 yerine 4 hanelidir ve kartın ön yüzünde yer alır. Güvenlik kodu giriş ekranlarınızın 4 haneli kodları da kabul edecek şekilde düzenlenmesi gerekmektedir.
<Card>\n\t<Number></Number>\n\t<ExpireDate></ExpireDate>\n\t<CVV2></CVV2>\n</Card>
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <Number> | Min: 15 - Max : 19 | Nümerik | Kart numarasının yollanıldığı alandır. |
| <ExpireDate> | 4 byte | MMYY (Ay ve Yılın son 2 hanesi) | Karta ait son kullanım tarihinin yollandığı alandır. |
| <CVV2> | Min : 3 Max : 4 (Amex) | Nümerik | Karta ait CVV bilgisinin yollanıldığı alandır. |
<Order> Etiketi ve Altında Yer Alacak Etiket ve Kuralları
Siparişe ait bilgilerin ve detayların yollanıldığı alandır.
<Order>\n\t<OrderID></OrderID>\n\t<GroupID />\n</Order>
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <OrderID> | 36 byte | Format zorunluluğu yok | Sipariş Numarasının yollandığı alandır. Sipariş bazlı unique (tek) olmalıdır. Firmalar tarafından üretilmelidir. |
| <GroupID> | 36 byte | Format zorunluluğu yok | Siparişleri kategorilendirmek(gruplamak) için kullanılan alandır. Örn : Kampanyalı gönderilen siparişler GroupID ye yazılan bir bilgi ile ayrıştırılabilir. |
<Transaction> Etiketi ve Altında Yer Alacak Etiket ve Kuralları
İşlem bilgilerinin ve finansal bilgilerin gönderildiği alanadır.
<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>
| Alt Etiket | Maks Boyut | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|---|
| <Type> | 32 byte | Alfanümerik | İşlem Tipinin gönderildiği alandır. Doküman içerisinde işlem tipleri ile ilgili detaylar ayrıca verilecektir. İşlem tipine göre diğer alanların kullanımına dikkat edilmelidir. |
| <InstallmentCnt> | 2 byte | Nümerik | Taksit sayısının girildiği alandır. |
| <Amount> | 17,2 number | 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 | Tutar bilgisinin girildiği alandır. |
| <CurrencyCode> | 3 byte | Nümerik | Kur bilgisinin yollanıldığı alandır. 949 -> TL diğer kurlar için yetkinize göre bilgilendirme yapılacaktır. |
| <CardholderPresentCode> | 2 byte | Nümerik | normal işlemler için 0, 3D işlemler için 13 girilmesi gerekmektedir. |
| <MotoInd> | 1 byte | Alfanümerik | Y ve N değerlerini alır. Ecommerce işlemler için N gönderilir. Moto işlem statüsündeki işlemler için Y gönderilir. |
| <InstallmentCnt> | 2 byte | Nümerik | Taksit sayısının girildiği alandır. |
Cevap (Response) Yapısı
Sanal POS 3D’siz Taksitli Satış işlemleri için, önceki başlıklarda gönderilen istek sonrası, servisten dönen cevap (response) yapısı aşağıdaki tabloda belirtilmiştir. Tablo içerisinde ilk kolonda yer alan ana tag altında yer alanabilecek her tag için gerekli olan bilgi ve açıklamalar incelenmeli ve istek mesajı bu tabloda belirtilen kurallara göre sağlanmalıdır:
Sanal POS taksitli satış işleminde cevap (response) yapısı genel biçimde aşağıdaki şekildedir:
<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<GarantiCardInd>Y</GarantiCardInd>\n\t</Transaction>\n</GVPSResponse>
Yukarıda verilen cevap yapısı içerisinde yer alan etiketler ve bu etiketlerin altında yer alan alt etiketler aşağıdaki başlıkta verilmiştir:
| Alt Etiket | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|
| <Mode> | PROD - TEST | İşlem modunun yazıldığı alandır |
| <Customer> | İstek yapısı içerisinde gönderilen müşteriye ait bilgilerin doğrulama amaçlı geri gönderildiği alandır. | |
| <Order> | Bu etiket kendi içerisinde alt etikeler barındırır. İçerdiği alt etiketler aşağıdaki başlıklarda verilmiştir. | |
| <Transaction> | Bu etiket kendi içerisinde alt etikeler barındırır. İçerdiği alt etiketler aşağıdaki başlıklarda verilmiştir. |
<Order> Etiketi Etiketi ve Altında Yer Alacak Etiket ve Kuralları
Request içerisinde gönderilen sipariş bilgilerinin, response içerisinde aynı şekilde döndüğü alandır.
<Order>\n <OrderID></OrderID>\n <GroupID></GroupID>\n</Order>
| Alt Etiket | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|
| <OrderID> | Alfanümerik | Sipariş numarasının geri döndürüldüğü alandır. |
| <GroupID> | Alfanümerik | GroupID numarasının geri döndürüldüğü alandır. Bu etiket alt etiketler içerir. Alt etiketlere ilişkin detaylar aşağıdaki başlıklarda verilmiştir. |
<Transaction> Etiketi Etiketi ve Altında Yer Alacak Etiket ve Kuralları
| Alt Etiketleri | Veri Yazım Formatı | Açıklama ve notlar |
|---|---|---|
| <Response> | Bu etiket alt etiketler içerir. Alt etiketlere ilişkin detaylar aşağıdaki başlıklarda verilmiştir. | |
| <RetrefNum> | Nümerik | Sanalpos tarafından üretilen işlem numarasının geri döndürüldüğü |
| <AuthCode> | Nümerik | Onay kodunun geri döndürüldüğü alandır. |
| <BatchNum> | İşlemlerin hangi batche gireceğinin geri döndürüldüğü alandır. | |
| <SequenceNum> | İşlem sıra numarası | |
| <ProvDate> | YYYYMMDD | Provizyon tarihinin döndürüldüğü alandır. |
| <CardNumberMasked> | Kart numarasının ilk 6 son 4 hanesinin, aradaki alanların * lı geri döndürüldüğü alandır. | |
| <CardHolderName> | Kart sahibinin adının gönderildiği alandır. | |
| <CardType> | İşlem yapılan kart tipinin dönüldüğü alandır. | |
| <HashData> | İşleme ait HashData bilgisinin dönüldüğü alandır. | |
| <HostMsgList> | Bu etiket alt etiketler içerir. Alt etiketlere ilişkin detaylar aşağıdaki başlıklarda verilmiştir. | |
| <RewardInqResult> | Bu etiket alt etiketler içerir. Alt etiketlere ilişkin detaylar aşağıdaki başlıklarda verilmiştir. | |
| <GarantiCardInd> |
Kod Örnekleri
Aşağıda farklı yazılım dilleri ile yazılmış sanal POS Peşin Satış işlem örneklerine github repo linkleri verilmiştir. Tercih ettiğiniz programlama diline ait link üzerinden ön tanımlı değerlerle yazılmış olan kodları inceleyebilirsiniz.
- C# Kod Örnekleri için tıklayınız.
- VB.Net Kod Örnekleri için tıklayınız.
- Java Kod Örnekleri için tıklayınız.
- PHP Kod Örnekleri için tıklayınız.
Kod Örnekleri
Aşağıda bu işlem tipinin de yer aldığı, farklı yazılım dilleri ile yazılmış özel kod örneklerine ait github repo linkleri verilmiştir. Tercih ettiğiniz programlama diline ait link üzerinden ön tanımlı değerlerle yazılmış olan kodları inceleyebilirsiniz.
- C# Kod Örnekleri için tıklayınız.
- VB.Net Kod Örnekleri için tıklayınız.
- Java Kod Örnekleri için tıklayınız.
- PHP Kod Örnekleri için tıklayınız.
Hata Kodları
Hata kodlarına bu sayfadan ulaşabilirsiniz.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsiniz.
