VPOS - 7/24 XML İşlem Tanımları Dokümanı V3.4

(1)

V3.4 VPOS 1

T. VAKIFLAR BANKASI T.A.O.

VPOS - 7/24 XML İşlem Tanımları Dokümanı V3.4

Banka VakıfBank

Proje Adı VPOS - 7/24

Doküman Referans No V3.4

Tarih 01/10/2013

(2)

VPOS724 XML İşlem Tanımları Kılavuzu3.4-v6.6 V3.4 VPOS 2 Bu doküman T.VAKIFLAR BANKASI T.A.O. tarafından hazırlanmış olup, bütün tasarım ve çoğaltma hakları T.VAKIFLAR BANKASI T.A.O.’ ya aittir. Dokümanın bütünü ya da herhangi bir kısmı, T.VAKIFLAR BANKASI T.A.O.’nun yazılı izni olmaksızın, çoğaltılamaz ve kaynak gösterilemez.

(3)

VPOS724 XML İşlem Tanımları Kılavuzu3.4-v6.6 V3.4 VPOS 3

Doküman Tarihçesi

Versiyon Yazan Açıklama Tarih

0.1 VakıfBank Vakıfbank VPOS 7/24 XML İşlem

Tanımları Kılavuzu3.4 hazırlandı. ^01/10/2013 1.0 VakıfBank Dağıtılabilir sürüm hazırlandı. 08/10/2013

2.0 VakıfBank Sorgulama Metodları eklendi 13/12/2013

3.0 VakıfBank SurchargeAmout alanı eklendi. Xml

Request ve Response değerleri eşitlendi. 17/04/2014 4.0 VakıfBank Eşleniksiz İade İsteği güncellendi 18/04/2014 5.0 VakıfBank CardHolderClientIp  ClientIp değişimi 27/04/2014 6.0 VakıfBank Surcharge Satış örnekleri eklendi 05/09/2014 6.1 VakıfBank Test ve Prod erişim linkleri eklendi 19/11/2014 6.2 VakıfBank Kredi Kartı Test işlemi örnek mesajları

eklendi 25/11/2014

6.3

VakıfBank Recurring işlemlerde taksit tablosunun dönülmesi sağlanmıştır.

Test Linkleri güncellenmiştir.

01/12/2014

6.4 VakıfBank Talimatlı işlemlerin sorgulanabilmesi için

gerekli xml tanımları eklenmiştir. 13.01.2015 6.5 VakıfBank API ile Talimat güncellenebilmesi için

gerekli xml tanımları eklenmiştir. 14.01.2015

6.6 VakıfBank Xml tanımları güncellendi. 14.01.2015

(4)

İçindekiler

1. Genel Açıklama ... 7

2. Genel Kurallar ... 8

3. Tanımlar ... 9

4. Sanal POS İşlem Tipleri ... 10

5. VPOS 7/24 XML Şema Bilgileri ... 11

6. İşlem İstek ve Cevap Parametre Zorunluluk Listesi ... 15

7. İşlem Kuralları ve XML Alan Ayrıntıları ... 17

8. İşlem Sonuç Kodları ... 20

9. Sanal POS İşlemleri ... 24

9.1. Peşin/Taksitli Satış (Sale) ... 25

9.1.1. Peşin Satış İsteği ... 25

9.1.2. Peşin Satış Cevabı ... 26

9.1.3. Taksitli Satış İsteği ... 27

9.1.4. Taksitli Satış Cevabı ... 27

9.1.5. Surcharge Satış İsteği ... 28

9.1.6. Surcharge Satış Cevabı ... 28

9.1.7. Peşin/Taksitli/Surcharge Satış İptal (Cancel) ... 28

9.2. İptal (Cancel) ... 29

9.2.1. İptal İsteği ... 29

9.2.2. İptal Cevabı ... 29

9.3. İade (Refund) ... 30

9.3.1. İade İsteği ... 30

9.3.2. İade Cevabı ... 30

9.3.3. İade İptal (Cancel) ... 31

9.4. Ön Provizyon (Auth) ... 31

9.4.1. Ön Provizyon İsteği ... 31

9.4.2. Ön Provizyon Cevabı ... 31

9.4.3. Ön Provizyon İptal (Cancel) ... 32

9.5. Provizyon Kapama (Capture) ... 32

9.5.1. Provizyon Kapama İsteği ... 32

9.5.2. Provizyon Kapama Cevabı ... 32

9.5.3. Provizyon Kapama İptal (Cancel) ... 33

9.5.4 Provizyon Kapama İade (Refund) ... 33

9.6. Puan Kullanma(PointSale) ... 33

9.6.1. Puan Kullanma İsteği ... 34

9.6.2. Puan Kullanma Cevabı ... 34

(5)

9.6.3. Puan Kullanma İptal (Cancel) ... 34

9.7. Puan Sorgu (PointSearch) ... 34

9.7.1. Puan Sorgu İsteği ... 35

9.7.2. Puan Sorgu Cevabı ... 35

9.8. VFT Satış (VFTSale) ... 35

9.8.1. VFT Satış İsteği ... 36

9.8.2. VFT Satış Cevabı ... 36

9.8.3. VFT Satış İptal (Cancel) ... 36

9.9. Vade Farklı Taksit Sorgusu (VFTSearch) ... 37

9.9.1. Vade Farklı Taksit Sorgu İsteği ... 37

9.9.2. Vade Farklı Taksit Sorgu Cevabı ... 37

9.10. Kampanya Sorgu (CampaignSearch) ... 38

9.10.1. Kampanya Sorgu İsteği ... 38

9.10.2. Kampanya Sorgu Cevabı ... 38

9.11. Teknik İptal (Reversal) ... 39

9.11.1. Teknik İptal İsteği... 39

9.11.2. Teknik İptal Cevabı ... 39

9.12. Recurring İşlemler (Recurring) ... 40

9.12.1. Recurring İşlem İsteği ... 40

9.12.2. Recurring İşlem Cevabı ... 41

9.13. Günsonu Kapama İşlemi (BatchClose) ... 41

9.13.1. Günsonu Kapama İsteği ... 42

9.13.2. Günsonu Kapama Cevabı... 42

9.14. Surcharge Sorgu (SurchargeSearch) ... 42

9.14.1. Surcharge Sorgu İsteği ... 42

9.14.2. Surcharge Sorgu Cevabı ... 43

9.18.1 Kredi Kart Test Sorgu İsteği ... 43

9.18.2 Kredi Kart Test Sorgu Cevabı ... 44

10. Sanal POS Sorgulama İşlemleri ... 45

10.1. Başarılı İşlem Sorgulama (SettlementDetail) ... 45

10.1.1. Başarılı İşlem Sorgu İsteği ... 45

10.1.2. Başarılı İşlem Sorgu Cevabı ... 45

10.2. Başarılı İşlem Kırılımı Sorgulama(Settlement) ... 46

10.2.1. Başarılı İşlem Kırılımı Sorgu İsteği ... 47

10.2.2. Başarılı İşlem Kırılımı Sorgu Cevabı ... 47

10.3. Kayıt Detay Sorgulama(Search) ... 49

10.3.1. Kayıt Detay Sorgu İsteği ... 49

10.3.2. Kayıt Detay Sorgu Cevabı ... 49

(6)

10.4. Gün Sonu Alınacak Kayıtlar Sorgulama ... 50

10.4.1. Gün Sonu Alınacak Kayıtlar Sorgu İsteği ... 50

10.4.2. Gün Sonu Alınacak Kayıtlar Sorgu Cevabı ... 51

10.5. Talimatlı İşlem Sorgulama ... 53

10.5.1. Talimatlı İşlem Sorgu İsteği ... 53

10.5.2. Talimatlı İşlem Sorgu Cevabı ... 53

10.6. Talimat Güncelleme ... 54

10.6.1. Talimat Güncelleme Sorgu İsteği ... 54

10.6.2. Talimat Güncelleme Sorgu Cevabı ... 55

(7)

1. Genel Açıklama

VPOS 7/24 (Sanal Pos) Uygulaması, alışveriş sitelerinde yapılan satış işlemlerinin Internet ortamı üzerinden Banka provizyonuna gönderilmesi için hazırlanmıştır.

Alışveriş sitesi kullanıcılarının seçtikleri ürünlerin tutarı ile sitede girdikleri kredi kartı bilgilerinin, VPOS 7/24 uygulamasına gönderilmesiyle satış işlemi provizyonu başlatılır.

VPOS 7/24 uygulaması da gerekli bilgileri hazırlayarak ilgili bankaya iletir ve girilen bilgilerin geçerliliğine göre olumlu ya da olumsuz cevap döndürür. Tüm işlemler internet ortamında yapıldıklarından, dönen cevap yine internet ortamından alışveriş sitesine iletilmektedir.

Alışveriş sitesinde geliştirme yapmaktan sorumlu olan üye iş yerlerinden aşağıdaki bilgileri VPOS 7/24 Uygulamasına göndermeleri beklenmektedir:

 Kullanıcıların alışverişlerinde aldıkları ürüne ait tutar bilgileri,

 Bankamız tarafında tanımlı olan üye işyeri kullanıcı adı ve şifre bilgileri

 Site kullanıcılarının girdikleri, o kredi kart numarası, o kartın son kullanma tarihi,

o kartın arkasında bulunan 3 Haneli CVV2 değeri.

o Amex kartlar için kullanılan güvenlik kodu kartın ön yüzünde bulunan, kart numarasının bitiminden sonra kartın sağına doğru yer alır.

VPOS 7/24 uygulaması yukarıda belirtilen bilgileri kullanarak banka ile haberleşip, işlem sonucunu yine belirlenmiş bir yapıda üye iş yerlerine dönmektedir.

VPOS 7/24 uygulaması ile

 Bankamız kredi kartlarına taksitli satış işlemi yapılabilir,

 Yapılan satış işlemlerinin tamamı ya da bir kısmı iade edilebilir,

 İşlem iptal edilebilir,

 Bankamız kartlarına puan bilgisi sorgulanabilir ve puan harcaması yapılabilir,

 Üye işyerlerinin kendilerine tanımlanmış kampanyalar sorgulanabilir.

Kart sahipleri VISA ve MasterCard’ın sunduğu 3-D Secure programı ile Internet ortamında güvenli alışveriş yapabilmeleri için tanımlayabilecekleri bir şifreyi de kullanabilirler.

VPOS 7/24 uygulamasında VISA, MasterCard ve Amex’e ait kredi ve banka kartları desteklenmektedir.

(8)

2. Genel Kurallar

Internet ortamında yapılan alışveriş işlemleri için kullanılacak olan VPOS 7/24 uygulaması Üye işyerlerinin internet ortamında güvenli ve kolay işlem yapabilmelerini sağlamak için geliştirilmiştir. Üye işyeri ile VPOS 7/24 uygulaması arasında iletişim protokolü olarak HTTPS kullanılacaktır. Üye işyeri VPOS 7/24’e ileteceği mesajları XML olarak hazırlayıp göndermelidir.

VPOS 7/24’te yapılan işlemlere dair genel kurallar aşağıdaki gibidir:

 Internet ortamında gönderilen işlemler, HTTPS (128 bit SSL) bağlantı üzerinden iletilmek zorundadır.

 VPOS 7/24 sistemine gönderilen her işlem farklı bir işlem numarası (TransactionId) içermelidir. Bu işlem numarası ile ilgili işleminin sonucu sorgulanmakta ve bu numara, referanslı işlemlerde (iptal, iade ve ön provizyon kapama) işlemlerinde referans olarak kullanılmaktadır. UIY tarafından, işlem numarası gönderilmediği takdirde sistem tarafından otomatik olarak bir işlem numarası atanmakta ve UIY’ne cevap olarak dönülmektedir.

 Üye işyeri XML mesajında gönderilmesi gereken işlem alanlarının tutarlı olması ve XML formatına uygun gönderilmesi zorunludur.

 VPOS 7/24 üzerinde işlemler online olarak gerçekleştirilir ve cevabı anında üye işyerine iletilir. Internet hatlarındaki kopukluklar ve benzer aksaklıklar yüzünden cevabı alınamayan işlemler, üye işyeri tarafından sorgulanmalı ve gerekli iptal işlemleri yapılmalıdır.

 VPOS 7/24 sistemi tarafından döndürülen cevaplar da XML formatında olacaktır.

 VPOS 7/24 sisteminde gün sonu işlemleri otomatik yapılır. ÜİY’nin günü kapatmak ya da başlatmak için herhangi bir işlem yapmasına gerek yoktur. İstenirse, manuel gün sonu kapatma gerçekleştirebilir.

 VPOS 7/24 sisteminden işlem cevabı olarak dönülen işlem numarası (TransactionId), ÜİY tarafından mutlaka saklanmalıdır. Bu numara, ilgili işlemin iptali ve sorgulanması sırasında kullanılmaktadır.

 ÜİY, VPOS 7/24 sistemine, herhangi bir işlemde işleme dair bir sipariş numarası göndermek istiyor ise bu bilgileri “OrderId” altında gönderebilir. Aynı OrderId bilgisine sahip sadece ve sadece 1 adet başarılı işlem bulunabilir. Belli bir sipariş numarası ile 1 adet başarılı işlem geçilmiş ise, mükerrerliği önlemek adına, aynı işlem numarası ile ikinci bir satış geldiği takdirde bu işlem, başarısız olarak cevaplanmaktadır. Öte yandan, belli bir sipariş numarası ile geçilen işlemler başarısız cevap almış ise, aynı sipariş numarası ile yeni işlemler gönderilebilmektedir.

(9)

3. Tanımlar

Tanım Açıklama

Üye İşyeri (UIY) Bankamızın güvenli VPOS 7/24 altyapısını kullanarak kredi kartı ile tahsilat yapacak tüm kurum veya kuruluşlar.

SurchargeRate Surcharge Oranı. Surchage Oran bilgisi şu formüle göre iletilir:

SurchargeOran = (SurchargeAmount/CurrencyAmount)*100

Mail Order Üye işyeri nin Mail order yapması için özel olarak yetkilendirildiği, API veya yönetim panelinden gönderilebilen CVV2 kontrolü yapılmayan işlem tipi.

Reversal Akıbeti bilinmeyen işlemler için HOST’a çıkılan teknik iptal mesajıdır.

Recurring

İlk işlem esnasında üye işyeri tarafından belirtilen periyot bilgilerine göre, belirli aralıklarla banka hostuna cvv2 siz, otomatik olarak gönderilen satış işlemidir.

POX Request

Plain Old Xml. Tüm kodlama dilleri ve Internet Protokolleri tarafından desteklenen, hazırlanmış olan bir xml in, basit bir şekilde ilgili uygulamaya post edilebildiği istek tipi

(10)

4. Sanal POS İşlem Tipleri

VPOS 7/24 uygulaması üzerinde aşağıdaki işlemler yapılabilmektedir.

 Satış / Taksitli Satış

 Ön Provizyon Açma

 Ön Provizyon Kapama

 Puan Harcama

 Vade Farklı Taksitli Satış

 Vade Farklı Taksit Sorgulama

 Puan Sorgulama

 Üye İşyeri Kampanya Sorgulama

 İade

 İptal

 Kredi Kart Test

 Yapılandırılmış Taksitli İşlem

 Tekrarlı Tahsilat Sistemi (Recurring İşlemler, Tekrar eden ödemeli işlemler)

 Reversal (Teknik İptal)

 Gün Sonu Geçme İşlemi

 Surcharge Sorgu

 Mutabakat Sorgu İşlemleri o Başarılı İşlem Sorgulama

o Başarılı İşlem Kırılımı Sorgulama o Kayıt Detay Sorgulama

o Gün Sonu Alınacak Kayıtlar Sorgulama

(11)

5. VPOS 7/24 XML Şema Bilgileri

VPOS 7/24 uygulamasına gönderilen XML mesajlarındaki alanların açıklamaları, Tablo 5-1’de gösterilmektedir.

XML alan adı Açıklama Alan biçimi

ve Uzunluğu

Alabileceği değer

VposRequest İşlem bilgileri bölümü - -

TransactionType İşlem adı bilgisi Boşluk içermemelidir. - Sale Cancel Refund Auth Capture Reversal CampaignSearch

BatchClosedSuccessSearch SurchargeSearch

VFTSale VFTSearch PointSearch PointSale CardTest

MerchantId Üye işyeri numarası Alfanumerik-15 -

Password Üye işyeri şifresi Alfanumerik +

Sembol TransactionId Benzesiz (Unique) İşlem numara bilgisi Alfanumerik-40

TerminalNo İşlemin hangi terminal üzerinden gönderileceği bilgisi Alfanumerik-8 ÜİY için tanımlanmış mevcut terminallerden herhangi birinin terminal numarası iletilmelidir. Ör:

VB007000,…

CurrencyAmount İşlem tutar bilgisi Sayısal(kuruş

hariç maks 10 basamaklı olabilir.)

Örnek: 55.00 ya da 145.34

SurchargeAmount Surchargelı işlem tutar bilgisi Sayısal(kuruş hariç maks 10 basamaklı olabilir.)

Örnek: 55.00 ya da 145.34

CurrencyCode İşlem kur bilgisi (YTL = 949) Sayısal –

Tamsayı - 3

TL=949 USD=840 EUR=978 JPY=392 GBP=826

PointAmount Puan tutarı Sayısal Örnek: 55.00 ya da 145.34

PointCode Puan birimi Sayısal TL = 949

NumberOfInstallments İşlem taksit sayısı Sayısal – Tam sayı – 2

Örnek: 1, 12, vb...

BrandName Kredi kartı kart kuruluşu bilgisi Sayısal 100: Visa

200: MasterCard 300: Amex

Pan Kredi kart numarası bilgisi Sayısal–15-22 Örnek: 4543600299100712

(12)

ve Uzunluğu

Expiry Kredi kartı son kullanma tarihi bilgisi Sayısal–6 YYYYMM

Cvv Kredi kartı güvenlik kodu bilgisi Sayısal–3 Örnek: 544

SecurityCode AMEX kartların ön yüzünde bulunan güvenlik numarasıdır

Sayısal-4 Örnek:9456

ReferenceTransactionId Orjinal işlem üye işyeri işlem numarası bilgisi Alfanumerik–40

CardHoldersName Kart sahibinin adı Alfanumerik–

100

ClientIp İşlemi yapan son kullanıcının IP si Üye iş yeri tarafından alınıp sanal posa gönderilecektir

Alfanumerik–15 Örnek: 78.155.195.43

OrderId Sipariş numarası işlem başarılı olana kadar aynı sipariş numarası sisteme gönderilebilir(UyeRefNo)

Alfanumerik–40 + Sembol

OrderDescription Sipariş ile ilgili varsa detaylı açıklama Alfanumerik- 2000 + Sembol

RecurringFrequencyType İşlemin hangi periyod tipinde tekrarlanacağı bilgisini içerir

Alfanumerik- Sabit

Day, (Günlük tekrarlama) Month, (Aylık tekrarlama) Year (Yıllık tekrarlama) RecurringFrequency İşlemin ne kadar sürede bir tekrarlanacağı bu alanda

belirtilir. RecurringFrequencyType ile birlikte bir anlam ifade eder

Sayısal

RecurringInstallmentCount Recurring işlemin toplamda kaç kere tekrar edeceği bilgisini içerir

Sayısal

CAVV MPI tarafından 3D Secure işlemin sonucunda gönderilen alan

Alfanumerik- 28 + Sembol

ECI 3D secure işlemin sonucu Sayısal Visa:05,06,07

MasterCard:01,02,03 CustomItems Üye işyeri tarafından işleme ait ek bilgiler varsa

CustomItems alanında gönderilir. İçeriğinde “Item”

listesi vardır

Complex

Item İşleme ait özel bilgiler içerir. İçeriğinde “name” ve

“value” attirbutelarını barındırır

Complex-500

DeviceType Raporlama amacıyla işlemin hangi kaynaktan gönderildiği bilgisi

Sayısal 1: Android 2: IOS 3: Windows Extract Bu alanda gönderilecek değer kart hamili ektresinde

işlem açıklamasında çıkacaktır. (Abone no vb.

bilgiler gönderilebilir)

Alfanumerik-40

ExpSign BKM Express İşlem Numarası Alfanumerik-40

MpiTransactionId İşlemin Mpi tarafındaki TransactionId numarası. Bu değer VPOS tarafından işlemin 3d bilgileirni kontrol etmek için kullanılır.

Alfanumerik-40

Location Raporlama amacıyla, işlemin gönderildiği yer bilgisi Sayısal 1:internet 2:Telefon 3:Mobile

4:Kurum muhasebe/erp sistemi 6:Kiosk

7:Diğer

(13)

ve Uzunluğu

TransactionDeviceSource İşlemin MailOrder ya da ECommerce olduğu belirtilir. Tüm provizyon isteklerinde gönderilmesi zorunludur. MailOrder işlem yetkiye bağlıdır ve işlem yetkisi yoksa sanalpos tarafından işlem

reddeilecektir. MailOrder isteklerde ECI ve CAVV değerleri gönderilmemelidir. ECI ve CAVV değeri sadece 3D ECommerce işlemlerde gönderilmelidir.

Sayısal 0:ECommerce

1:MailOrder

Tablo 5-1 VPOS 7/24 e iletilecek Xml Şeması

VPOS 7/24 uygulamasından cevap olarak gönderilen XML mesajlarındaki alanların açıklamaları Tablo 5-2’de gösterilmektedir.

XML alan adı Açıklama Alan biçimi ve

Uzunluğu

Alabileceği değer

VposResponse İşlem bilgileri bölümü - -

TransactionType Requestte gönderilen TransactionType geri gönderilecektir.

- Sale

Cancel Refund Auth Capture Reversal CampaignSearch CardTest

BatchClosedSuccessSearch SurchargeSearch

VFTSale VFTSearch PointSearch PointSale MerchantId Requestte gönderilen MerchantId geri

gönderilecektir.

Alfanumerik-15 -

TransactionId Requestte gönderilen TransactionId gönderilmediyse Sanal Pos tarafından oluşturulan TransactionId geri gönderilecektir.

Alfanumerik-40

ReferenceTransactionId Requestte gönderilen ReferenceTransactionId geri gönderilecektir.

Alfanumerik–40 Request işlemi

ResultCode İşlemin sonucu Alfanumerik-4 0000,2011 v.b..

ResultDetail İşlemin sonucuna ilgili varsa detaylı bilgi Alfanumerik- 100

AuthCode Banka tarafından işlemin cevabında dönülen kod

Alfanumerik-50

HostDate İşlemin banka tarafında gördüğü tarih ve saat bilgisini içerir

Alfanumerik-10 yymmddhhmm formatında olacaktır

Rrn İşlemin bank tarafındaki referans

numarası

Alfanumerik-12

CustomItems Sanal pos tarafından işleme ait ek bilgiler varsa CustomItems alanında gönderilir.

İçeriğinde “Items” listesi vardır

Complex

Item İşleme ait özel bilgiler içerir. İçeriğinde

“name” ve “value” attirbutelarını barındırır

Complex

(14)

XML alan adı Açıklama Alan biçimi ve

Uzunluğu

Alabileceği değer

Name İşleme ait özel bilginin adı Alfanumerik CUSTOMMESSAGE,

MAXIPOINT, MILPOINT, TOTALMAXIPOINT, TOTALMILPOINT,

INSTALLMENTTRANSACTIONAMOUNT, DISCOUNTEDAMOUNT

Value İşleme ait özel bilginin değerini içerir Alfanumerik- degişken NumberOfInstallments İşlemin taksit sayısı Sayısal – tam Sayı - 2

CurrencyAmount İşlem Tutarı Sayısal

VftAmount Vade Farklı Tutar Sayısal

SurchargeAmount Surcharge tutarı Sayısal

CurrencyCode Param birimi Sayısal – 3

InstallmentTable İşlem sonucunda bir taksit hesaplaması yapılırsa taksit tablosu bu alanda geri dönülecektir “InstallmentItem“ listesi barındırır

Complex

InstallmentItem Taksit tablosuna ait bilgileri içerir.

İçeriğinde “Date”, “Amount” attribute larını barındırır

Complex

Date Taksite ait tarih bilgisini içerir Alfanumerik-8 yyyyMMdd

IsSurcharge İletilen işlem, Surcharge operasyonuna uğrayıp uğramadığı bilgisi

Sayısal 1: Surcharge’lı İşlem ise,

ThreeDSecureType 3D Secure işlem tipi Sayısal NonSecure = 1, Secure = 2, HalfSecure = 3

CampaignTable Kampanya bilgisi Alfa numerik

GainedPoint İşlem sonucunda kazanılan puan bilgisi Sayısal TotalPoint İşlem sonucunda kalan puan bilgisi Sayısal

Tablo 5-2 VPOS 7/24 tarafından cevap olarak gönderilen XML Şeması

(15)

6. İşlem İstek ve Cevap Parametre Zorunluluk Listesi

Tablolarda yer alan Z: Zorunlu, O: Opsiyonel, X: Olmayacak anlamındadır.

VPOS 7/24 uygulamasına iletilecek istek parametreleri İşlem Tipi bazlı zorunluluk listesi, Tablo 6-1‘da belirtilmiştir.

XML ALAN ADI VPOS Request

Sale Auth Capture PointSale VFTSale VFTSearch PointSearch CampaignSearch Refund Cancel Recurring işlem Reversal BatchClose SurchargeSearch

TrancactionType Z Z Z Z Z Z Z Z Z Z Z Z Z Z

MerchantId Z Z Z Z Z Z Z Z Z Z Z Z Z Z

TerminalNo Z Z Z Z Z Z Z Z Z Z Z Z Z Z

Pasword Z Z Z Z Z Z Z Z Z Z Z Z Z Z

Pan Z Z X Z Z Z Z X X X Z X X X

Expiry Z Z X Z Z Z Z X X X O X X X

CVV / SecurityCode O O X O O O O X X X O X X X

CurrencyAmount Z Z Z X Z Z X X Z X Z X X Z

CurrencyCode Z Z X X Z Z X X X X Z X X Z

NumberOfInstallments O O X X Z O X X X X Z X X X

BrandName O O X O O O O X X X O X X X

ECI O O X O O O O X O O O X X X

CAVV O O X O O O O X O O O X X X

PointAmount X X X Z X X X X O X O X X X

PointCode X X X Z X X X X O X O X X X

OrderId O O O O O O O X O O O X O O

TransactionID O O O O O O O X O O O O O O

ReferenceTranscationId X X Z X X X X X Z Z X Z X X

ExpSign O O X O O X X X O X O X X X

Ekstract O O X O O X X X O X O X X X

CardHoldersName O O X O O X X X O O O X X X

OrderDescription O O X O O X X X O O O O O X

CustomItems O O X O O X X X O O O O X X

IsRecurring O O X O O X X X X X Z X X X

O O X O O O O X O O O O X X

ClientIp Z Z Z Z Z Z Z X Z Z Z Z X X

DeviceType O O X O O O O X O O O X O O

Location O O X O O O O X O O O X O O

TransactionDeviceSource Z Z X Z Z X X X X X Z X X X

Tablo 6-1 İşlem İstek Parametre Zorunluluk Listesi

(16)

VPOS724 XML İşlem Tanımları Kılavuzu3.4-v6.6 V3.4 VPOS 16 VPOS 7/24 uygulamasından alınacak cevap parametreleri İşlem Tipi bazlı zorunluluk listesi,

Tablo 6-2‘da belirtilmiştir.

Tablo 6-2 İşlem Cevap Parametre Zorunluluk Listesi

XML ALAN ADI VPOS Response

Sale Auth Capture PointSale VFTSale VFTSearch PointSearch CampaignSearch Refund Cancel Credit Reversal BatchClose SurchargeSearch

TransactionType Z Z Z Z Z Z Z Z Z Z Z Z Z Z

TerminalNo X X X X X X X X X X X X X X

TransactionId Z Z Z Z Z Z Z Z Z Z Z Z Z Z

ResultCode Z Z Z Z Z Z Z Z Z Z Z Z Z Z

ResultDetail Z Z Z Z Z Z Z Z Z Z Z Z Z Z

AuthCode Z Z Z Z Z Z Z O Z Z Z X X Z

HostDate Z Z Z Z Z Z Z Z Z Z Z Z Z Z

Rrn Z Z Z Z Z Z Z Z Z Z Z Z Z Z

CustomItems O O O O O X X X O O O O O X

NumberOfInstallments Z O X X Z O X X O Z X X X X

CurrencyAmount Z Z Z X Z Z X X Z Z Z X X Z

VFTAmount X X X X Z Z X X O O X X X X

SurchargeAmount O O O X X X X X O O X X X Z

PointAmount X X X Z X X Z X O O X X X X

CurrencyCode Z Z Z X Z Z X X Z Z Z X X Z

PointCode X X X Z X X X X O O X O X X

InstallmentTable O O O X Z Z X X O O X O X X

IsSurcharge O O O O O X X X O O X O X O

ThreeDSecurityType Z Z Z Z Z X X X Z Z Z Z X X

CampaignTable O O O O O X O Z Z Z X X X O

GainedPoint Z Z Z Z Z X Z X Z Z X X X X

TotalPoint Z Z Z Z Z X Z X Z Z X X X X

Ekstract O O O O O X X X O O X X X X

DeviceType O O X O O X X X O X O X X X

Location O O O O O O O X O X X X X X

TransactionDeviceSource Z Z Z Z Z X X X X X Z Z X X XML ALAN ADI

VPOS Response

Sale Auth Capture PointSale VFTSale VFTSearch PointSearch CampaignSearch Refund Cancel Credit Reversal BatchClose SurchargeSearch

TransactionType Z Z Z Z Z Z Z Z Z Z Z Z Z Z

TerminalNo X X X X X X X X X X X X X X

TransactionId Z Z Z Z Z Z Z Z Z Z Z Z Z Z

ResultCode Z Z Z Z Z Z Z Z Z Z Z Z Z Z

ResultDetail Z Z Z Z Z Z Z Z Z Z Z Z Z Z

AuthCode Z Z Z Z Z Z Z O Z Z Z X X Z

HostDate Z Z Z Z Z Z Z Z Z Z Z Z Z Z

Rrn Z Z Z Z Z Z Z Z Z Z Z Z Z Z

CustomItems O O O O O X X X O O O O O X

NumberOfInstallments Z O X X Z O X X O Z X X X X

CurrencyAmount Z Z Z X Z Z X X Z Z Z X X Z

VFTAmount X X X X Z Z X X O O X X X X

SurchargeAmount O O O X X X X X O O X X X Z

PointAmount X X X Z X X Z X O O X X X X

CurrencyCode Z Z Z X Z Z X X Z Z Z X X Z

PointCode X X X Z X X X X O O X O X X

InstallmentTable O O O X Z Z X X O O X O X X

IsSurcharge O O O O O X X X O O X O X O

ThreeDSecurityType Z Z Z Z Z X X X Z Z Z Z X X

CampaignTable O O O O O X O Z Z Z X X X O

GainedPoint Z Z Z Z Z X Z X Z Z X X X X

TotalPoint Z Z Z Z Z X Z X Z Z X X X X

Ekstract O O O O O X X X O O X X X X

DeviceType O O X O O X X X O X O X X X

Location O O O O O O O X O X X X X X

TransactionDeviceSource Z Z Z Z Z X X X X X Z Z X X

(17)

7. İşlem Kuralları ve XML Alan Ayrıntıları

VPOS 7/24 işlemleri sırasında uygulanan kurallar ve işlemler sırasında kullanılan alan ayrıntıları aşağıdaki gibidir:

1. İşlem Numarası (TransactionId): VPOS 7/24 sistemine gönderilen her işlem farklı bir işlem numarası (TransactionId) içermelidir. Bu işlem numarası ile, ilgili işleminin sonucunu sorgulamakta ve iptal, iade veya ön provizyon kapama işlemlerinde referans olarak kullanılmaktadır. İşlem numarası gönderilmediği takdirde sistem tarafından otomatik olarak bir işlem numarası atanmakta ve UIY’ne cevap olarak dönülmektedir. TransactionId bilgisi alfanümerik bir alandır. TransactionId alanı istenilen karakter (alfanümerik) dizisinden oluşturulabilir fakat “ “ (boşluk) karakteri ve türkçe karakterler içermemelidir. Herhangi bir işlemin iptali, iadesi veya kapaması (captura) sırasında bu bilgi ReferenceTransactionId alanında VPOS 7/24 sistemine gönderilmelidir. Bu bilgi hatalı gönderildiği ya da gönderilmediği takdirde ilgili iptal, iade veya ön provizyon kapama işlemi yapılamayacaktır. Bu sebeple, işlem numarası, üye işyeri tarafından mutlaka saklanmalıdır.

2. Terminal Numarası (TerminalNo): Bankamız tarafından ÜİY ne verilen sanal POS numarasıdır. İşlemin provizyona hangi terminal üzerinden iletileceği bilgisidir.

3. İşlem Tipi (TransactionType): Gönderilecek işlemin tipidir. Alabileceği değerler Tablo 5-1‘de belirtilmiştir.

Bu alan kesinlikle boşluk içermemelidir.

4. ÜİY Şifresi (Password): Sanal mağazanın tanımlanmış olan işyeri şifresi Password alanında gönderilmelidir.

5. Taksitli İşlemler (NumberOfInstallments): Üye işyeri taksitli işlem yapmaya yetkili ise satış işlemlerini taksitli olarak gerçekleştirebilecektir. İşlem için taksit bilgisi NumberOfInstallments isimli alandan gönderilecektir. Taksit sayısı pozitif tamsayı olmalı ve üye işyeri çalışma şartlarında tanımlanan taksit aralıklarında yer almalıdır.

6. İşlem Kur Bilgisi (CurrencyCode): VPOS 7/24 sisteminde yapılan işlemler Türk Lirası ve diğer yabancı para birimleri üzerinden yapılabilmektedir. CurrencyCode alanında Türk Lirası için 949 gönderilmelidir.

Puan kullanma işlemlerinde ise puan türüne göre ilgili puan kodu gönderilmelidir. Bkz: Tablo 7-1

7. İşlem Tutar Bilgisi (CurrencyAmount): VPOS 7/24 sisteminde yapılan işlemlerde tutar bilgisi, kuruş bilgisini de içerek şekilde gönderilmeli, bir başka deyişle tutar bilgisinde Nokta(.)’dan sonra 2 anlamlı basamak mutlaka yer almalıdır. Örneğin 23.00 ya da 250.45 gibi. Kuruş hariç en fazla 10 basamaklı olabilir.

Para Birimi Kodu

TL 949

USD 840

EUR 978

JPY 392

GBP 826

Tablo 7-1 İşlem Kur Bilgisi

(18)

8. Kart Tipi Bilgisi (BrandName): Üye işyerleri herhangi bir işlemde kullanılan kart türünü BrandID alanında göndermelidir. BrandName alanında kartın türüne göre ilgili bilgi gönderilmelidir. (Visa, Master Card, American Express). Bkz: Tablo 7-2

9. Son Kullanma Tarihi (Expiry): Kredi kartının son kullanma tarihi bilgisidir. Formatı yyyyMM (201901) olmalıdır.

10. CVV2 (Cvv): Kredi kartının arka bölümünde bulunan üç haneli rakamlardır.

11. Orijinal İşlem Bilgisi (ReferenceTransactionId): İptal veya iade edilecek olan satış işleminin TransactionId’sidir. İade veya iptal işleminin ayrıca kendi benzersiz (unique) TransactionId’si olmalıdır.

Bu alan boşluk içermemelidir.

12. ECI (ECI): 3D Secure işlemlerde kullanılan Mpi tarafından gönderilen ECI kullanılır.

13. CAVV (CAVV): 3D Secure işlemlerde MPI tarafından gönderilen CAVV değeri kullanılır

14. Sipariş Numarası (OrderId): ÜİY, herhangi bir işlemde işleme dair bir sipariş numarası göndermek istiyor ise bu bilgileri “OrderId” altında gönderebilir. Aynı OrderId bilgisine sahip sadece ve sadece 1 adet başarılı işlem bulunabilir. Belli bir sipariş numarası ile 1 adet başarılı işlem geçilmiş ise, mükerrerliği önlemek için, aynı işlem numarası ile ikinci bir satış geldiği takdirde bu işlem, başarısız olarak cevaplanmaktadır.

15. Sipariş Detayı (OrderDescription): Üye işyeri OrderId gönderdiği herhangi bir işleme siparişle ilgili olan açıklama alanı ekleyebilir.

16. Kart Sahibi Adı (CardHoldersName): Üye işyeri alış verişi yapan kart sahibinin adını VPOS 7/24’e bu alanda gönderebilir.

17. Alışverişi Yapan Son Kullanıcının Ip si (ClientIp): Üye işyeri siteden alışverişi yapan kişinin Ip sini tespit ederek VPOS 7/24’e bu alanda gönderebilir.

18. İşlem Kaynağı Bilgisi (DeviceType): İşlemin hangi kaynaktan gönderildiği bilgisidir. Raporlama amacıyla kullanılmaktadır. 1: Android, 2:IOS, 3:Windows

19. Ekstre Bilgisi (Extract): Raporlama ve Sorgulama Ekranlarında burada iletilen bilgilerle sorgulama yapılabilmektedir. (Abone no vb. bilgiler gönderilebilir)

20. BKM Express İşlem Numarası (ExpSign): BKM Express üzerinden gerçekleştirilmiş işlemler için, BKM Express numarası yazılmalıdır.

21. Mpi İşlem Numarası (MpiTransactionId): VPOS bu alan aracılığıyla gönderilen ECI ve CAVV değerlerini GET 7/24 MPI dan sorgulayarak kontrol eder.

Kart Tipi Bilgisi Kart Tipi Kodu

Visa 100

Master Card 200

American Express 300

Tablo 7-2 Kart Tipi Bilgisi

(19)

22. İşlem Yeri Bilgisi (Location): İşlemin hangi uygulama/modül/yerden gönderildiği bilgisidir. Raporlama amacıyla kullanılmaktadır. 1:internet 2:Telefon 3:Mobile 4:Kurum muhasebe/erp sistemi 5:Mail Order 6:Kiosk 7:Diğer

23. Recurring İşlemin Tekrarlanma Tipi (RecurringFrequencyType): Üye işyeri Recurring işaretlediği işlemin tekrarlanma sıklık tipini belirtmek zorundadır. 3 çeşit tekrarlanma sıklığı bulunmaktadır. Günlük (Day), Aylık(Month) ve Yıllık(Year).

24. Recurring İşlemin Tekrarlanma Sıklığı (RecurringFrequency): Üye işyeri işlemi recurring olarak işaretledikten sonra tekrarlanma sıklığını belirtmek zorundadır. Tekrarlanma sıklığı RecurringFrequencyType ile beraber bir anlam ifade etmektedir.

25. Recurring İşlemin Toplam Kaç Kez Tekrarlanacağı (RecurringInstallmentCount): Üye işyeri işlemi recurring olarak işaretledikten sonra işlemin kaç kez tekrarlanacağı belirtmek zorundadır.

26. İşlem Sonuç Bilgisi (ResultCode): VPOS 7/24 sistemine gönderilen her işlem, gerekli kontrollerden geçirildikten ve ilgili işlem gerçekleştirildikten sonra bir cevap bilgisi ile üye işyerine gönderilir. İşlemin sonucuna dair temel bilgi ResultCode alanında verilmektedir.

İşlem sonuç bilgisini içeren 4 haneli bir koddur. Başarılı işlemler için bu değer “0000” dır. İşlem sırasında oluşan hatalara dair kodlar da bu alandan gönderilir. Hata ve uyarı kodları “İşlem Sonuç Kodları” başlığı altında anlatılmıştır.

27. İşlem Sonuç Detayı (ResulDetail): VPOS 7/24 sistemi her işlemin cevabında işleme ait cevap koduna dair bir açıklamayı üye işyerine döner.

28. Otorizasyon/Provizyon Kodu (AuthCode): Başarılı işlemlerde ana sistem tarafından döndürülen otorizasyon kodudur.

29. Referans Numarası (Rrn) : İşlemin banka tarafındaki referans numarasını belirtir. Banka tarafından VPOS 7/24’e iletilen Rrn numarası üye işyerine gönderilir.

30. İşlemin Bankamız Sisteminde Yapıldığı Saat (HostDate): İşlemin bankada sisteminde yapıldığı saati belirtir. VPOS 7/24 tarafında üye işyerine gönderilir.

31. İşlem Sonucuna Gönderilmiş Özel Alanlar (CustomItems): İşlemin sonucuna ait ek bilgiler bu alanda gönderilir. (Puan sorgulama sonucunda kart sahibinin kaç puanının olduğu puan kullanımdan sonra kaç puanı kaldığı ya da Banka tarafından gönderilmiş özel mesaj (CUSTOMMESSAGE) v.b. ) CustomItems ın içerisinde Item listesi bulunur. Item listesinin içerisindeki “name” ve “value” alanları gönderilen özel parametrelerin ismi ve değeri okunabilir.

32. Surcharge İşlem Bilgisi (IsSurcharge): İletilen işlemin, Surcharge operasyonuna uğrayıp uğramadığını ÜİY’ne bildiren alandır. 1: Surcharge’lı İşlem, 2: Surcharge’sız işlem

33. Surcharge İşlem Detayı(Surcharge): İletilen işlem, Surcharge operasyonuna uğramış ise, yapılan işlem hakkında bilgi dönülür.

(20)

8. İşlem Sonuç Kodları

Başarılı işlem cevabı 0000’dır. Hatalı işlemler için VPOS 7/24’ün döndürdüğü hata kodları Tablo 8-1’de gösterilmektedir.

Kod Açıklama

0000 Başarılı

0001 BANKANIZI ARAYIN 0002 BANKANIZI ARAYIN

0003 ÜYE KODU HATALI/TANIMSIZ 0004 KARTA EL KOYUNUZ

0005 İŞLEM ONAYLANMADI.

0006 HATALI İŞLEM 0007 KARTA EL KOYUNUZ 0009 TEKRAR DENEYİNİZ 0010 TEKRAR DENEYİNİZ 0011 TEKRAR DENEYİNİZ 0012 Geçersiz İşlem 0013 Geçersiz İşlem Tutarı 0014 Geçersiz Kart Numarası 0015 MÜŞTERİ YOK/BIN HATALI 0021 İŞLEM ONAYLANMADI

0030 MESAJ FORMATI HATALI (ÜYE İŞYERİ) 0032 DOSYASINA ULAŞILAMADI 0033 SÜRESİ BİTMİŞ/İPTAL KART 0034 SAHTE KART

0036 İŞLEM ONAYLANMADI 0038 ŞİFRE AŞIMI/KARTA EL KOY 0041 KAYIP KART- KARTA EL KOY 0043 ÇALINTI KART-KARTA EL KOY 0051 LIMIT YETERSIZ

0052 HESAP NOYU KONTROL EDİN 0053 HESAP YOK

0054 VADE SONU GEÇMİŞ KART 0055 Hatalı Kart Şifresi

0056 Kart Tanımlı Değil.

0057 KARTIN İŞLEM İZNİ YOK 0058 POS İŞLEM TİPİNE KAPALI 0059 SAHTEKARLIK ŞÜPHESİ 0061 Para çekme tutar limiti aşıldı 0062 YASAKLANMIŞ KART 0063 Güvenlik ihlali