Ödeme İsteği Gönderme İşlemi
Servis Adresi
/PaymentUserPos/CreateUserPosPayment
İstek Parametreleri
PaymentDealerAuthentication
| Parametre | Açıklama |
|---|---|
| DealerCode(string) | Moka sistemi tarafından verilen bayi kodu |
| Username (string) | Moka sistemi tarafından verilen Api kullanıcı adı |
| Password (string) | Moka sistemi tarafından verilen Api şifresi |
| CheckKey (string) | Kontrol anahtarı (DealerCode + "MK" + Username + "PD" + Password) String olarak birleştirilen bu bilgilerin SHA-256 hash algoritmasından geçirilmesiyle oluşturulur. Buraya tıklayarak deneme ekranına gidebilirsiniz. |
PaymentUserPosRequest
| Parametre | Açıklama | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| OtherTrxCode (string) | 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. | ||||||||
| DealerCustomerTypeId (integer) | 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. | ||||||||
| FullName (string) | Ödeme link’ inin gönderileceği müşterinizin adı soyadı - Link müşterinize gönderilmeyecek, servisle size dönecekse bu alanı girmeyebilirsiniz. | ||||||||
| GsmNumber (string) | Ödeme link’ inin gönderileceği telefon numarası - Link müşterinize gönderilmeyecek, servisle size dönecekse bu alanı girmeyebilirsiniz. | ||||||||
| Email (string) | Ödeme link’ inin gönderileceği email adresi - Link müşterinize gönderilmeyecek, servisle size dönecekse bu alanı girmeyebilirsiniz. | ||||||||
| IsPoolPayment (tinyint) | Havuz ödemesi mi ? 0 : Hayır - Karttan çekilen tutar, Moka ile bayi arasındaki anlaşmaya göre ertesi gün veya daha sonra bayinin hesabına yatırılı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. Bayi, havuz ödemesini onaylayıncaya kadar, bu ödeme ekstreye dahil edilmez. Havuz sisteminde bir ödeme göndermek için bu alanı 1 yapınız. |
||||||||
| IsPreAuth (tinyint) | Ön provizyon işlemi mi ? 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) |
||||||||
| IsTokenized (tinyint) | Ödeme için girilen kart Moka sisteminde saklanacak mı ? (Kart saklayabilmek için bayinin kart saklama hizmeti alıyor olması gerekir) 0 : Kart saklanmayacak 1 : Kart mutlaka saklanacak 2 : Kartının saklanıp saklanmayacağına ödeme yapan müşteri karar verecek |
||||||||
| DealerCustomerId (integer) | Daha önceden bu müşteri Moka sistemine kaydedilmişse, Moka sistemindeki bu müşterinin Unique ID si. | ||||||||
| CustomerCode (string) | Bu müşterinin, sizin sisteminizdeki Unique ID si. Bu kod Moka'ya 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 | ||||||||
| FirstName (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin adı girilir. | ||||||||
| LastName (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin soyadı girilir. (opsiyonel) | ||||||||
| Gender (tinyint) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin cinsiyeti girilir. (opsiyonel) 1: erkek 2: kadın | ||||||||
| BirthDate (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin doğum tarihi girilir. (opsiyonel) | ||||||||
| CustomerGsmNumber (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin cep telefonu girilir. (opsiyonel) | ||||||||
| CustomerEmail (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin email adresi girilir. (opsiyonel) | ||||||||
| Address (string) | Müşteri Moka sistemine ilk kez kaydedilecekse, müşterinin ikamet adresi girilir. (opsiyonel) | ||||||||
| Amount (decimal) | Ödeme tutarı (Kuruş kısmı nokta ile yazılır. Örn: 27.50) | ||||||||
| Currency (string) | Para birimi. Opsiyonel alandır, hiç gönderilmezse veya boş gönderilirse, default’ u TL dir, Diğer değerler : USD, EUR, GBP | ||||||||
| InstallmentNumber (integer) | Taksit Sayısı. Opsiyonel alandır, hiç gönderilmezse, boş gönderilirse, 0 veya 1 gönderilirse Peşin satış demektir, Taksit için 2 ile 12 arasında bir değer gönderilmelidir. | ||||||||
| SetInstallmentBy (tinyint) | 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ı |
||||||||
| CommissionByDealer (tinyint) | 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. |
||||||||
| IsCommissionDiffByDealer (tinyint) | Ü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) |
||||||||
| IsThreeD (tinyint) | Ö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 |
||||||||
| Description (string)(opsiyonel) | Açıklama alanıdır. Ödemeye ilişkin bir açıklama yazmak istenirse bu alana yazılabilir.(200 karaktere kadar yazılabilir.) | ||||||||
| ReturnHash (tinyint) | Değeri 1 olarak verilmek zorundadır. 3D Ödeme akışı tamamlandığında, RedirectURL' nize, işlemin başarılı olup olmadığı bu servisin cevabında dönen CodeForHash kodunun sonuna, T veya F harfi eklenerek hash' lenmesi ile bildirilecektir. | ||||||||
| RedirectUrl (string) | Ödemenin yapılacağı Link, müşteriye gönderilmeyecekse, servisle size geri dönecek ve siz bu linki kendiniz açacaksanız, o zaman RedirectUrl
alanını vermeniz gerekir. Link, SMS veya email ile müşterinin kendisine yollanacaksa, ödeme sonucu Moka' nın kendi sayfasına yönlendirileceğinden bu alanı vermenize gerek yoktur. 3D işlemi sonucunda, başarılı ya da başarısız işlem sonucunun döndürüldüğü ve kullanıcının yönlendirildiği bayi web sayfası. Bu URL’ yi verirken, sonuna parametre olarak kendi işlem ID’ nizi yazarsanız, hangi işleminizin sonucunu aldığınızı belirlemiş olursunuz. OtherTrxCode alanını gönderiyorsanız, URL' yi verirken Get parametresi kullanmasanız da olur. OtherTrxCode alanı bu URL' ye POST atılıyor zaten. Örnek : https://www.mysite.com/PayResult?MyTrxId=1A2B3C4DF5R Önemli Not : URL sonuna yazdığınız kendinize ait işlem kodunun, güvenliğiniz için, tahmin edilemez bir kod olmasını tercih ediniz. |
||||||||
| BuyerInformation (Array)(opsiyonel) | Bayimizden Ürün/Hizmet satın alan müşterisi ile ilgili alanlardır. Bu alanların gönderilmesi zorunlu olmamasına karşın, Moka ile paylaşılması,
ileride ödemeyle ilgili oluşabilecek sorunlara karşı, hem bayimizin hem de Moka' nın menfaatinedir.
|
||||||||
| BasketProduct (Array)(opsiyonel) |
|
Örnek İstek (JSON)
{
"DealerAuthentication":{
"DealerCode":"XXX",
"Username":"XXX",
"Password":"XXX",
"CheckKey":"28ba1f316e661ee7a0477a13aa30613da548c94a8098829af9255b04d7e916e3"
},
"PaymentUserPosRequest":{
"OtherTrxCode":"78687676",
"DealerCustomerTypeId":"2",
"FullName":"Zeynep",
"GsmNumber":"",
"Email":"zeynep.hashan@moka.com",
"IsPoolPayment":"0",
"IsPreAuth":"0",
"IsTokenized":"0",
"DealerCustomerId":"",
"CustomerCode":"",
"FirstName":"",
"LastName":"",
"Gender":"0",
"BirthDate":"19901218",
"CustomerGsmNumber":"",
"CustomerEmail":"",
"Address":"",
"Amount":"0.01",
"Currency":"TL",
"InstallmentNumber":"0",
"SetInstallmentBy":"0",
"CommissionByDealer":"",
"IsCommissionDiffByDealer":"0",
"IsThreeD":"0",
"Description":"",
"ReturnHash":1,
"RedirectUrl":"https://service.TestMoka.com/PaymentDealerThreeD?MyTrxCode=78687676",
"BuyerInformation":{
"BuyerFullName":"",
"BuyerGsmNumber":"",
"BuyerEmail":"",
"BuyerAddress":"Tasdelen"
}
}
}
Başarılı İstek Sonucu
- 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) ve de URL linki bulunur. Başarısız olmuş ise, Data alanı null olacaktır. ResultCode ve ResultMessage alanları kontrol edilerek hatanın sebebi yorumlanabilir.
- Ödeme ekranını açacak olan bu link SMS veya Email ile kart sahibine gönderilmemişse, üye iş yeri tarayıcıyı bu linke yönlendirilmelidir.
- Ödeme ekranını üye işyeri, kendisi, kart sahibinin tarayıcısında açtırıyorsa, RedirectUrl ile ödeme sonucunu da kendisi alacaktır. Ve alttaki işlemleri de yapacaktır.
- Data bloğu içerisindeki CodeForHash verisini ise, Moka, ödeme sonucunu bildirmek için kullanacaktır. Bu değeri de veri tabanınızda saklayınız ve bu ödeme isteğiyle ilişkilendiriniz.
- Kullanıcı kart doğrulama işlemini tamamladıktan sonra, servis çağrılırken gönderilen "RedirectUrl" linkine otomatik olarak geri yönlendirilir. Yani sizin verdiğiniz URL’ ye Post atılır
- Bu yönlendirme sırasında "hashValue", "resultCode", "resultMessage", "trxCode" ve "OtherTrxCode" form alanları okunarak işlemin sonucuna göre gerekli işlemler gerçekleştirilebilir.
- Bankadan başarılı işlem dönmesi durumunda trxCode alanı içinde dönen OrderId saklanmalıdır. İptal, iade veya havuz ödeme onayı işlemleri, bu kod kullanılarak gerçekleştirilecektir.
- Ödemenin başarısız olması durumunda ise başarısızlık nedeni "resultCode" ve "resultMessage" alanları kullanılarak öğrenilebilir.
- hashValue nasıl hesaplanır ve kontrol edilir ?
-
3D Onaylama sonucu sizin RedirectURL’ nize TEXT POST atılarak dönen değerler:
Key : hashValue Value : cdb7869505bdaaac2f4c891fc9ed889885fd7a0c880127ab5d508883efa3ee83
Key : resultCode Value :
Key : resultMessage Value :
Key : trxCode Value : ORDER-17131QQFG04026575
Key : OtherTrxCode Value : Your-Transaction-Code -
Ödeme sonucunu ayrıca başka bir URL' ye TEXT POST atmamızı isterseniz, bunu Moka operasyon ekibine bildirebilirsiniz.
Post attığımız URL' den text olarak "OK" cevabı gelirse ödeme sonucunun üye işyerine Post atılabildiği anlaşılır, diğer türlü Post işlemi 2 kez daha denenir.
Sizin vereceğiniz bir URL' ye, her ödemenin tamamlanmasında şu bilgiler POST atılır :
Key : hashValue Value : cdb7869505bdaaac2f4c891fc9ed889885fd7a0c880127ab5d508883efa3ee83
Key : resultCode Value :
Key : resultMessage Value :
Key : trxCode Value : ORDER-17131QQFG04026575
Key : OtherTrxCode Value : Your-Transaction-Code
Başarılı Sonuç Örneği
{
"Data":{
"UserPosPaymentId":3393,
"DealerCustomerId":0,
"Url":"https://pos.testmoka.com/CustomerPos/PaymentRequest?uppc=57681",
"CodeForHash":"9FDFBDFC-42C5-417E-AA93-E4D9D5312AAC"
},
"ResultCode":"Success",
"ResultMessage":"",
"Exception":null
}
Başarısız İstek Sonucu
Gönderilen istek verileri Moka akışları içerisinde işlenemediyse, geri dönüş nesnesinin "ResultCode" alanında alttaki tablodaki hata kodlarından birisi bulunur.
Beklenmeyen yazılımsal bir hata oluştuğunda ise, "ResultCode" alanında EX yazar ve "ResultMessage" alanında alınan hata mesajı (Exception) yer alır.
Her iki durumda da, "Data" nesnesi null olarak gelir.
| ResultCode | Açıklama |
|---|---|
| PaymentUserPos.DealerAuthentication.InvalidRequest | CheckKey hatalı ya da nesne hatalı ya da JSON bozuk olabilir. |
| PaymentUserPos.DealerAuthentication.InvalidAccount | Böyle bir bayi bulunamadı. |
| PaymentUserPos.CreateUserPosPayment.ChannelPermissionNotAvailable | Bayinin, ödeme isteği gönderme yetkisi yok. |
| PaymentUserPos.CreateUserPosPayment.IpAddressNotAllowed | Bayinin erişebileceği IP ler kısıtlanmış. |
| PaymentUserPos.CreateUserPosPayment.EmailOrGsmNumberRequired | Ödeme linki gönderilecek email veya telefon verilmemiş. |
| PaymentUserPos.CreateUserPosPayment.GsmRequired | Ödeme linki gönderilecek telefon verilmemiş. |
| PaymentUserPos.CreateUserPosPayment.EmailRequired | Ödeme linki gönderilecek email verilmemiş. |
| PaymentUserPos.CreateUserPosPayment.InvalidGsmNumber | Ödeme linki gönderilecek telefon numarası yanlış |
| PaymentUserPos.CreateUserPosPayment.InvalidEmailFormat | Ödeme linki gönderilecek email formatı yanlış |
| PaymentUserPos.CreateUserPosPayment.InvalidCustomerGsmNumber | Kart saklama hizmeti için, bayi müşteri bilgisi olan telefon bilgisi yanlış |
| PaymentUserPos.CreateUserPosPayment.InvalidCustomerEmailFormat | Kart saklama hizmeti için, bayi müşteri bilgisi olan email bilgisi yanlış |
| PaymentUserPos.CreateUserPosPayment.InvalidCurrencyCode | Para birimi yanlış (TL, USD, EUR veya GBP olmalı) |
| PaymentUserPos.CreateUserPosPayment.InstallmentNotAvailableForForeignCurrencyTransaction | Yabancı para için taksit yapılamaz. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerTypeNotFound | Böyle bir ödeme isteği gönderme tanımı bulunamadı. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerTypeMismatchForDealer | Bu ödeme isteği gönderme tanımı, bu bayiye ait değil. |
| PaymentUserPos.CreateUserPosPayment.ForeignCurrencyUnavailable | Bayinin, yabancı para izni yok. |
| PaymentUserPos.CreateUserPosPayment.InvalidPaymentPermission | Ön otorizasyon veya doğrudan ödeme göndermeye ilişkin hata mesajı |
| PaymentUserPos.CreateUserPosPayment.InvalidPoolPermission | Havuzlu ödeme göndermeye ilişkin hata mesajı |
| PaymentUserPos.CreateUserPosPayment.InvalidTokenizationPermissionValue | Kart saklamaya ilişkin hata mesajı |
| PaymentUserPos.CreateUserPosPayment.InvalidTokenizationPermission | Bayinin kart saklama izni yok |
| PaymentUserPos.CreateUserPosPayment.InvalidCommissionByDealerValue | Kaç takside kadar komisyon bayiden, değeri, yanlış verilmiş |
| PaymentUserPos.CreateUserPosPayment.InvalidCommissionDiffByDealerValue | Daha fazla taksitlerde komisyon farkı kimden, değeri, yanlış verilmiş |
| PaymentUserPos.CreateUserPosPayment.SetInstallmentByAndInstallmentNumberInconsistent | Taksit seçimini kim yapacak, bayi mi, müşteri mi ? Tanım ile verilen değer uyumlu olmalı |
| PaymentUserPos.CreateUserPosPayment.InvalidInstallmentNumber | Taksit sayısı yanlış girilmiş. |
| PaymentUserPos.CreateUserPosPayment.SetInstallmentByInconsistent | Taksit seçimini kim yapacak, bayi mi, müşteri mi ? Tanım ile verilen değer uyumlu olmalı |
| PaymentUserPos.CreateUserPosPayment.ThreeDRequired | 3D zorunlu olmalı |
| PaymentUserPos.CreateUserPosPayment.InvalidBirthDateFormat | Bayi müşterisinin bilgilerinden, doğum tarihi yanlış girilmiş. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerNotCreated | Yeni bir bayi müşterisi oluşturulmaya çalışıldı ancak hata alındı. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerNotFound | Mevcut bir bayi müşterisi gönderildi (CustomerCode ile), ancak bu müşteri bulunamadı. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerInfoIsMissing | Bayi müşterisi oluşturmak için en azından CustomerCode ve FirstName verilmeli. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerIdAndCustomerCodeDontMatchForDealer | Hem Moka sistemindeki DealerCustomerId verilmiş hem de bayinin kendi Müşteri kodu verilmiş. Ama Moka sisteminde bu müşteri verileri uyumsuz |
| PaymentUserPos.CreateUserPosPayment.InvalidBuyerGsmNumber | Hizmet alan kişiye ait alanlarda sorun var. |
| PaymentUserPos.CreateUserPosPayment.InvalidBuyerEmailFormat | Hizmet alan kişiye ait alanlarda sorun var. |
| PaymentUserPos.CreateUserPosPayment.DailyDealerLimitExceeded | Bayinin günlük ödeme limiti aşıldı. |
| PaymentUserPos.CreateUserPosPayment.MonthlyDealerLimitExceeded | Bayinin aylık ödeme limiti aşıldı. |
| EX | Beklenmeyen bir hata oluştu |
Başarısız Sonuç Örneği
{
"Data": null,
"ResultCode": "PaymentUserPos.CreateUserPosPayment.GsmRequired",
"ResultMessage": "",
"Exception": null
}
Açıklama
Üye İş Yeri, Müşteri tipinde CommunicationType alanı aşağıdaki şekillerde belirlenebilir.
Eğer;
0: Hem SMS hem de Email açık olmasını, üye iş yerinin dilediğini veya her ikisini de girebilmesini istiyorsanız,
1: Sadece SMS’den ödeme isteği göndermek istiyorsanız,
2: Sadece Email’den ödeme isteği göndermek istiyorsanız,
3: SMS veya Email atılmadan sadece ödemenin yapılabileceği link (URL) ile ödeme isteği göndermek istiyorsanız
Belirtilen değerler verilmelidir.
CommunicationType alanı değişikliği için satış yöneticinizle görüşerek ya da operasyon@moka.com adresinden mail göndererek bize ulaşabilirsiniz.