Ödeme İsteği Gönderme İşlemi
Servis Adresi
POST /PaymentUserPos/CreateUserPosPayment
İstek Parametreleri
PaymentDealerAuthentication
| Parametre | Açıklama |
|---|---|
| DealerCode string | Ruut sistemi tarafından verilen bayi kodu |
| Username string | Ruut sistemi tarafından verilen Api kullanıcı adı |
| Password string | Ruut 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 | Ruut 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, Ruut 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 Ruut 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 Ruut sistemine kaydedilmişse, Ruut sistemindeki bu müşterinin Unique ID si. | ||||||||
| CustomerCode string | Bu müşterinin, sizin sisteminizdeki Unique ID si. Bu kod Ruut'a 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 Ruut sistemine ilk kez kaydedilecekse, müşterinin adı girilir. | ||||||||
| LastName string | Müşteri Ruut sistemine ilk kez kaydedilecekse, müşterinin soyadı girilir. (opsiyonel) | ||||||||
| Gender tinyint | Müşteri Ruut sistemine ilk kez kaydedilecekse, müşterinin cinsiyeti girilir. (opsiyonel) 1: erkek 2: kadın | ||||||||
| BirthDate string | Müşteri Ruut sistemine ilk kez kaydedilecekse, müşterinin doğum tarihi girilir. (opsiyonel) | ||||||||
| CustomerGsmNumber string | Müşteri Ruut sistemine ilk kez kaydedilecekse, müşterinin cep telefonu girilir. (opsiyonel) | ||||||||
| CustomerEmail string | Müşteri Ruut sistemine ilk kez kaydedilecekse, müşterinin email adresi girilir. (opsiyonel) | ||||||||
| Address string | Müşteri Ruut 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 Ruut' 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, Ruut ile paylaşılması,
ileride ödemeyle ilgili oluşabilecek sorunlara karşı, hem bayimizin hem de Ruut' 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@ruutapp.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.TestRuut.com/PaymentDealerThreeD?MyTrxCode=78687676",
"BuyerInformation":{
"BuyerFullName":"",
"BuyerGsmNumber":"",
"BuyerEmail":"",
"BuyerAddress":"Tasdelen"
}
}
}
Başarılı İstek Sonucu
- Gönderilen istek verileri Ruut’ 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, Ruut, ö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 Ruut 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.testruutapp.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 Ruut 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 Ruut sistemindeki DealerCustomerId verilmiş hem de bayinin kendi Müşteri kodu verilmiş. Ama Ruut 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@ruutapp.com adresinden mail göndererek bize ulaşabilirsiniz.