MOKA ÖDEME SERVİSİ ÖDEME İSTEĞİ GÖNDERME BAYİ ENTEGRASYON DOKÜMANI V 1.0 MAYIS 2018 Abdullah APAYDIN - Elif YETİMOĞLU Sayfa 1
Test Domain: https://service.testmoka.com Prod Domain: https://service.moka.com Servislerin Çağrılması: Moka servisleri JSON POST yöntemiyle çalışmaktadır. Aşağıda her bir servis için verilen servis adresleri test ya da prod domain lerin sonuna eklenerek oluşan URL e, yine aşağıda her bir servis için detaylı bir şekilde örnekleriyle verilen parametreler JSON nesnesi olarak POST edilir. ÖNEMLİ!!! Servislerimiz PCI-DSS kuralları gereği sadece TLS 1.1 ve TLS 1.2 protokollerinin kullanımına izin vermektedir. Lütfen uygulamanızın bu protokoller üzerinden Moka URL sine POST attığından emin olunuz. Aksi taktirde Bağlantı kapatılacaktır veya Connection Closed şeklinde hatalar alınacaktır. Servislerden Yanıt Alınması: Moka servisleri yanıt olarak ApiResponse nesnesi döner. Bu nesnenin ResultCode ve Data alanları okunarak akışlar yönetilebilir. ApiResponse Data ResultCode ResultMessage Exception : Gönderdiğiniz istek Moka ya doğru bir şekilde iletilmiş, kullanıcı bilgileri doğru bir şekilde girilmiş ve girilen bilgiler Moka tarafında herhangi bir uyarıya veya hataya yol açmamışsa, Data alanı dolu gelecektir. Data alanı içinde size dönen verileri kullanarak işlem sonucunu yorumlayabilirsiniz. : Gönderilen veriler Moka tarafında bir uyarıya veya hataya yol açmışsa, Data alanı null olarak gelecektir ve ResultCode alanında Moka hata kodu yer alacaktır. : Hataya ilişkin özel bir açıklama var ise bu alan dolu olacaktır. : Beklenmedik bir hata oluştuğunda ResultCode alanında EX yazacaktır ve Exception alanında alınan hatanın açıklaması yer alacaktır. Sayfa 2
Servis Adı Servis Adresi İstek Parametreleri ÖDEME İSTEĞİ GÖNDERME İŞLEMİ /PaymentUserPos/CreateUserPosPayment DealerAuthentication DealerCode Username Password CheckKey Moka sistemi tarafından verilen bayi kodu Moka sistemi tarafından verilen kullanıcı adı Moka sistemi tarafından verilen şifre Kontrol anahtarı (DealerCode + MK + Username + PD + Password) bilgileriyle elde edilen anahtar SHA-256 hash algoritmasından geçirilerek bu alanda gönderilecektir PaymentUserPosRequest OtherTrxCode DealerCustomerTypeId (integer) FullName GsmNumber Email IsPreAuth IsPoolPayment IsTokenized DealerCustomerId (integer) CustomerCode FirstName LastName Gender Mütabakat sağlamak için kendi Unique Transaction (İşlem) Kodunuzu bu alanda göndermelisiniz. Not : Bayi ödeme detay listesi alırken bu kodunuzu kullanarak Ödeme durumunu öğrenebilirsiniz. Moka tarafından bayinize özel oluşturulmuş Ödeme İsteği gönderme tanım kaydının ID si. Bu tanımdaki kurallara göre ödeme isteğini göndermelisiniz. Aksi taktirde hata mesajları alacaksınız. Ödeme link inin gönderileceği müşterinizin adı soyadı Ödeme link inin gönderileceği telefon numarası Ödeme link inin gönderileceği email adresi 0 : Hayır - Doğrudan Çekim İşlemi 1 : Evet - Ön Provizyon Alma İşlemi (Bir süre sonra DoCapture servisi ile ödemeye dönüştürülmeli) 0 : Hayır 1 : Evet - Para kredi kartından çekilecek fakat havuzda bekletilecek. Bayi, müşteri hizmet veya ürünü teslim aldıktan sonra ödemeyi onaylayacak ve bu işlemle ilgili ödeme onaydan sonra bayinin ekstresine yansıyacak. Havuz sisteminde bir ödeme göndermek için bu alanı 1 yapınız. 0 : Kart saklanmayacak 1 : Kart mutlaka saklanacak 2 : Kartının saklanıp saklanmayacağına ödeme yapan müşteri karar verecek Daha önceden bu müşteri Moka sistemine kaydedilmişse, Moka sistemindeki bu müşterinin Unique ID si. Bu müşterinin, sizin sisteminizdeki Unique ID si. Bu kod Mokaya daha önceden kaydedilmişse, bu kod ile de ödeme isteği gönderebilirsiniz ve kart saklanacaksa, bu müşteri altında saklanır. Bu müşteri ilk kez kaydedilecekse, bu kod ile kaydedilir. adı girilir. soyadı girilir. (opsiyonel) cinsiyeti girilir. (opsiyonel) 1: erkek 2: kadın Sayfa 3
BirthDate doğum tarihi girilir. (opsiyonel) CustomerGsmNumber cep telefonu girilir. (opsiyonel) CustomerEmail email adresi girilir. (opsiyonel) Address ikamet adresi girilir. (opsiyonel) Amount (decimal) Ödeme tutarı (Kuruş kısmı nokta ile yazılır. Örn: 27.50) Currency Para birimi. Opsiyonel alandır, hiç gönderilmezse veya boş gönderilirse, default u TL dir, Diğer değerler : USD, EUR, GBP InstallmentNumber Taksit Sayısı. Opsiyonel alandır, hiç gönderilmezse, boş (integer) gönderilirse, 0 veya 1 gönderilirse Peşin satış demektir, SetInstallmentBy CommissionByDealer IsCommissionDiffByDe aler IsThreeD Description BuyerInformation (Array)(opsiyonel) Taksit için 2 ile 12 arasında bir değer gönderilmelidir. Taksitli ödemelerde, taksit sayısını kimin seçeceğini belirler. 0 : Taksit sayısını müşteri seçecek 1 : Taksit sayısını ödemeyi gönderen bayi seçip yolladı Komisyon bayi tarafından mı ödenecek, yoksa müşteriye mi yüklenecek? 0 : Hem peşin hem de taksitli ödemelerin hepsinde komisyonu Müşteri ödeyecek. Bayi komisyona karışmaz. 1 : Sadece peşin ödemede komisyonu bayi öder, taksitlerde komisyonu müşteri öder. 2 : Hem peşin hem de 2 taksitte, komisyonu bayi öder, daha yüksek taksitlerde komisyon müşteriden alınır. 3 : Hem peşin hem de 2 taksitte, komisyonu bayi öder, daha yüksek taksitlerde komisyon müşteriden alınır... 12 : Hem peşin hem de bütün taksitlerde, komisyonu bayi öder. Üstte yer alan, kaç takside kadar komisyonu bayinin ödeyeceği bilgisine göre, daha fazla taksitlerde, komisyonun tamamı ya da sadece aradaki fark müşteriye yansıtılabilir. 0 : Hayır (Seçilen Taksit Komisyonunun Tamamını Müşteriye Yansıt) 1 : Evet (Seçilen Taksit Komisyonu (eksi) Bayinin Karşılamayı Kabul Ettiği Taksit Komisyonu kadar komisyonu (Fark Komisyonu) Müşteriye Yansıt) Ödeme işlemi 3D kullanılarak mı yapılacak? 0 : 3D zorunlu değil (müşteri isterse non-3d ödeme yapar, isterse de 3D seçenegini işaretleyebilir) 1 : 3D kullanılarak ödeme yapılmasi zorunlu Açıklama alanıdır (opsiyonel). Ödemeye ilişkin bir açıklama yazmak istenirse bu alana yazılabilir.(200 karaktere kadar yazılabilir.) BuyerFullName Opsiyonel alandır. Hizmeti Alan kişinin adı ve soyadıdır. Sayfa 4
BuyerEmail Opsiyonel alandır.alıcının e- posta adresidir. BuyerGsmNumber Opsiyonel alandır.alıcının cep telefonu numarasıdır. BuyerAddress Opsiyonel alandır.alıcının adresidir. Örnek İstek (JSON) Başarılı İstek Sonucu Başarılı Sonuç Örneği Başarısız İstek Sonucu { "DealerAuthentication":{"DealerCode":"MFW","Username":"Moka","Password":"Moka2532","Ch eckkey":"28ba1f316e661ee7a0477a13aa30613da548c94a8098829af9255b04d7e916e3"},"payme ntuserposrequest":{"othertrxcode":"123456","dealercustomertypeid":"1","fullname":"ahmet Yılmaz","GsmNumber":"5352345678","Email":"ahmet@hotmail.com","IsPreAuth":"0","IsPoolPay ment":"0","istokenized":"2","dealercustomerid":"","customercode":"abc123","firstname":"ah met","lastname":"yılmaz","gender":"1","birthdate":"","customergsmnumber":"5352345678","c ustomeremail":"ahmet@hotmail.com","address":"istanbul","amount":"4.45","currency":"tl","in stallmentnumber":"1","setinstallmentby":"1","commissionbydealer":"12","iscommissiondiffbyd ealer":"0","isthreed":"1","description":"abonelik","buyerinformation":{"buyerfullname":"ahmet Yılmaz","BuyerGsmNumber":"5352345678","BuyerEmail":"ahmet@hotmail.com","BuyerAddress" :"Tasdelen"}} } Gönderilen istek verileri Moka da başarılı bir şekilde işlenmişse, geri dönüş nesnesinin "ResultCode" alanında Success bilgisi yazar. Data alanında ise gönderilen ödeme isteğinin ID si (UserPosPaymentId) ve de eğer kart saklama ihtimali var ise, yeni oluşturulan veya zaten mevcut olan bayi müşterisinin ID si (DealerCustomerId) döner. Başarısız olmuş ise, Data alanı null olacaktır. ResultCode ve ResultMessage alanları kontrol edilerek hatanın sebebi yorumlanabilir. {"Data":{"UserPosPaymentId":2036,"DealerCustomerId":332}, "ResultCode":"Success", "ResultMessage":"","Exception":null} Gönderilen istek verileri Moka da başarılı bir şekilde işlenemediyse, geri dönüş nesnesinin ResultCode alanında alttaki tablodaki hata kodlarından birisi bulunur. Data nesnesi ise null olarak gelir. ResultCode Açıklama PaymentUserPos.DealerAuthentication. Hatalı hash bilgisi InvalidRequest PaymentUserPos.DealerAuthentication. Böyle bir bayi bulunamadı InvalidAccount Bayinin, ödeme isteği gönderme yetkisi yok ChannelPermissionNotAvailable Bayinin erişebileceği IP ler kısıtlanmış IpAddressNotAllowed Ödeme linki gönderilecek email veya telefon EmailOrGsmNumberRequired verilmemiş. Ödeme linki gönderilecek telefon verilmemiş. GsmRequired Ödeme linki gönderilecek email verilmemiş. EmailRequired Ödeme linki gönderilecek telefon numarası InvalidGsmNumber yanlış Ödeme linki gönderilecek email formatı yanlış InvalidEmailFormat Kart saklama hizmeti için, bayi müşteri bilgisi InvalidCustomerGsmNumber olan telefon bilgisi yanlış InvalidCustomerEmailFormat Kart saklama hizmeti için, bayi müşteri bilgisi olan email bilgisi yanlış Sayfa 5
Başarısız Sonuç Örneği InvalidCurrencyCode InstallmentNotAvailableForForeignCur rencytransaction DealerCustomerTypeNotFound DealerCustomerTypeMismatchForDealer ForeignCurrencyUnavailable InvalidPaymentPermission InvalidPoolPermission InvalidTokenizationPermissionValue InvalidTokenizationPermission InvalidCommissionByDealerValue InvalidCommissionDiffByDealerValue SetInstallmentByAndInstallmentNumber Inconsistent InvalidInstallmentNumber SetInstallmentByInconsistent ThreeDRequired InvalidBirthDateFormat DealerCustomerNotCreated DealerCustomerNotFound DealerCustomerInfoIsMissing DealerCustomerIdAndCustomerCodeDontM atchfordealer Para birimi yanlış (TL, USD, EUR veya GBP olmalı) Yabancı para için taksit yapılamaz Böyle bir ödeme isteği gönderme tanımı bulunamadı Bu ödeme isteği gönderme tanımı, bu bayiye ait değil. Bayinin, yabancı para izni yok Ön otorizasyon veya doğrudan ödeme göndermeye ilişkin hata mesajı Havuzlu ödeme göndermeye ilişkin hata mesajı Kart saklamaya ilişkin hata mesajı Bayinin kart saklama izni yok Kaç takside kadar komisyon bayiden, değeri, yanlış verilmiş Daha fazla taksitlerde komisyon farkı kimden, değeri, yanlış verilmiş Taksit seçimini kim yapacak, bayi mi, müşteri mi? Tanım ile verilen değer uyumlu olmalı Taksit sayısı yanlış girilmiş Taksit seçimini kim yapacak, bayi mi, müşteri mi? Tanım ile verilen değer uyumlu olmalı 3D zorunlu olmalı Bayi müşterisinin bilgilerinden, doğum tarihi yanlış girilmiş. Yeni bir bayi müşterisi oluşturulmaya çalışıldı ancak hata alındı Mevcut bir bayi müşterisi gönderildi (CustomerCode ile), ancak bu müşteri bulunamadı Bayi müşterisi oluşturmak için en azından CustomerCode ve FirstName verilmeli Hem Moka sistemindeki DealerCustomerId veilmiş hem de bayinin kendi Müşteri kodu verilmiş. Ama Moka sisteminde bu müşteri verileri uyumsuz Hizmet alan kişiye ait alanlarda sorun var InvalidBuyerGsmNumber Hizmet alan kişiye ait alanlarda sorun var InvalidBuyerEmailFormat Bayinin günlük ödeme limiti aşıldı DailyDealerLimitExceeded Bayinin aylık ödeme limiti aşıldı MonthlyDealerLimitExceeded EX Beklenmeyen bir hata oluştu {"Data":null,"ResultCode":"GsmRequired", "ResultMessage":"","Exception":null} Sayfa 6