Entegrasyon
Son güncelleme 22 Eylül 2024.Ödeme Entegrasyon Servisleri
1. Ortak Ödeme Sayfası
İstenen değerler post edilerek işlemler Nkolay Ortak Ödeme sayfasına yönlendirilir. Kart bilgileri doğrudan Nkolay sunucularına gider, güvenlik Nkolay tarafından sağlanır. Site içinde iframe ile entegrasyon yapılabilir.
Ortak Ödeme Sayfası ile Ödeme Alma
2. Linkli Ödeme
Ödeme linki kart kullanıcısına SMS veya e-posta ile gönderilir. Kullanıcı linke tıklayarak Nkolay Ortak Ödeme sayfasına yönlendirilir, işlemler burada gerçekleşir.
Ödeme linki kart kullanıcısına SMS veya e-posta ile gönderilir. Kullanıcı linke tıklayarak Nkolay Ortak Ödeme sayfasına yönlendirilir, işlemler burada gerçekleşir.
3. API - Kart Bilgilerinin Üye İşyeri Tarafından Alındığı Yapı
Üye işyeri kendi sayfasında kart bilgilerini alır, Nkolay API ile işlem yapar. Bu yapıda kart bilgileri üye işyeri tarafından alındığı için PCI DSS gereklilikleri üye işyerine aittir.
Ortak Ödeme Sayfası Sanal POS Kullanımı
Sanal POS uygulamamız, Anlaşmalı firmaların Pay N Kolay hizmeti ile online ödeme almasını sağlar.
Kendi uygulamanız üzerinden ödeme alabilmeniz için aşağıda, sizlere özel verilen değerler http POST metodu ile Test ortam URL : https://paynkolaytest.nkolayislem.com.tr/Vpos adresine post edilerek gönderilir. Prod ortam URL’i : https://paynkolay.nkolayislem.com.tr/Vpos ‘dir.
Form Değişkenlerine ait bilgiler
Servise POST edilmesi gereken parametreler aşağıdaki gibidir. Parametrelerin tümü body’de post edilmelidir.
Uygulama akışı1. Formda gönderdiğiniz bilgilerin geçerlilik kontrolü yapılır, eksik veya hatalı bilgi varsa hata mesajı dönülür ve akış sonlanır.
2. Formda gönderdiğiniz bilgiler kontrol edilir. Doğru değil ise hata mesajı ile akış sonlanır.
3. Formda gönderdiğiniz bilgiler doğru ise, kredi kartı bilgilerinin girileceği form gösterilir.
4. Formda kredi kartı kart bilgisi girildikten sonra bu kutucuktan ayrılırken taksit seçenekleri görüntülenir. Tek çekim varsayılan olarak seçili gelir.
5. Kredi kartı bilgilerinin tamamı girilip uygun taksit seçeneği işaretlendikten sonra "Ödemeyi Gerçekleştir" tuşuna basılarak ödeme işlemi gerçekleştirilir.
6. Ödeme işlemi 3D olacak ise akış 3D sayfasına yönlendirilir, 3D değilse direk sonuçlanır.
7. Ödeme işlemi başarılı sonuçlanmış ise "successUrl" sayfasına başarılı sonuç değerleri post edilerek yönlendirilir.
8. işlem başarısız olursa başarısız işlem bilgileri “failURL” sayfasına post edilir.
| İsim | Tipi | Açıklama | Zorunlu | Örnek Değer |
|---|---|---|---|---|
| sx | string | Web Servis için gerekli olan giriş kodudur. Kod’un içinde gerekli parametreler şifrelenmiş bir şekilde mevcuttur. Bu alan size Ödeme kuruluşu tarafından verilecektir. | *Zorunlu | 114488219|SjEH1wb6qoqWtN2X9/5Y6H9YIJIpRxySQ== |
| amount | decimal | Ödeme tutarıdır. Kuruş ayracı olarak . (nokta) kullanılmalıdır. | *Zorunlu | 1280.10 ( kuruş ayracı olarak nokta kullanılmalıdır. ) |
| clientRefCode | string | Referans Numarası (Türkçe karaketer içermemeli. En fazla 1024 karaktere kadar olabilir.) | *Zorunlu | Örn: 5231As-FE2A36|896585654|891-98 |
| successUrl | string | Bu sayfaya başarılı işlemlerin sonucunu post ediyoruz. | *Zorunlu | https://domaininiz.com.tr/success |
| failUrl | string | Bu sayfaya başarılı olmayan işlemlerin sonucunu post ediyoruz. | *Zorunlu | https://domaininiz.com.tr/fail |
| second | int | Sepetinde kalan süreyi ( session time out süreniz ) Sanal POS’ta göstermek isterseniz kalan saniyeyi post edebilirsiniz. Sayfamızda sepetiniz için kalan saniyeyi geri sayım olarak gösteriyoruz. Süre bitince ödeme butonunu disable ediyoruz. | İsteğe Bağlı | 600 |
| cardcampaign | int | Dilerseniz Visa, Master Kartlara kampanya yapabilirsiniz. Visa kartlar için 4, MasterCard için 5 parametresini göndermeniz gerekmektedir. Şayet müşterinin kredi kartı numarası ilgili rakam değilse, müşteriye uyarı verilmekte ve sadece istediğiniz kart numarası ile başlayan kartlara ödeme için izin verilmektedir. | İsteğe Bağlı | 4 ( Visa ) ya da 5 ( Master Card ) |
| bin | string | Dilerseniz sadece belirli kart bin’lerinden işlem alabilirsiniz. ( Kartın ilk 6 hanesidir. ) Dilerseniz tek kart bini, dilerseniz birden fazla bini aralarında pipe | işareti ile ayırarak gönderebilirsiniz. | İsteğe Bağlı | 413278|521089|432617 |
| language | string | Dil seçeneği olarak İngilizce için “en”, Rusça için “ru” girilmelidir. Bir parametre gönderilmez ise dil Türkçe demektir. | İsteğe Bağlı | en |
| detail | string | “true” gönderilirse sanal pos ortak ödeme sayfasında müşterinizden alabileceğiniz ( Ad Soyad (inputNamesurname), TC Kimlik No (inputTckn), Cep Telefonu (inputPhone), Email Adresi (inputEmail), Açıklama ( inputDescription ) ve Adres (inputAddress) ) input alanları ödeme sayfasında gözükecektir. Bu input alanlarını diğer değişkenlerle bize POST ederseniz, Açıklama alanınlarını otomatik dolduruyoruz. | İsteğe Bağlı | true |
| agentCode | string | Alt bayilik üzerinden işlem yapılıyorsa bu değer ile alt bayinizin kodunu gönderebilirsiniz. | İsteğe Bağlı | 7683323 |
| use3D | string | “true” gönderilirse 3D secure limitinden bağımsız bir şekilde işlemi 3D secure yaptırır. Boş gönderilirse mevcut 3D işlem limiti uygulanır. | *Zorunlu | true |
| transactionType | string | “sales” yani satış ya da “presales” provisyon olarak işlem yapabilirsiniz. | *Zorunlu | sales |
| rnd | string | DateTime.Now fonksiyonu ile işlem tarihini bize göndermeniz gerekmektedir. ( Bu değer işlem sonucunda size geri post edilecektir. ) | *Zorunlu | 09-08-2021 15:24:22 |
| instalments | number | Kaç taksit girilirse ödeme işlemi o taksit sayısı ile yapılacaktır. Örneğin: 2 girilmesi, 2 taksittir. 1 girilirse ödeme işlemleri tek çekim yapılacaktır ( taksit yapılmayacaktır ) Boş geçilmesi durumunda default ödeme alma ayarlarına göre taksitleri gelecektir. | İsteğe Bağlı | |
| hashData | string | PHP ile : $hashstr = $sx . $clientRefCode . $amount . $successUrl . $failUrl . $rnd . $merchantSecretKey; $hashData = base64_encode(pack('H*',sha1($hashstr))); .net hesaplaması aşağıda verilmiştir. | *Zorunlu | BH51O7coM4dtd/WoRMNg4o8H2XPI= |
| MerchantCustomerNo | string | MerchantCustomerNo ile sanal pos'a bayi veya alt üye işteri numaranızı gönderebilirsiniz. Pay N Kolay panelinden işlemlerinizi Müşteri Numarası başlığı altında bu numara ile aratabilirsiniz. (clientRefCode'un uzun ve karmaşık olduğu durumlarda kullanmakta fayda vardır.) | İsteğe Bağlı | 93423410 |
| customerKey | string | Ortak ödeme sayfası ile kart saklama yapılabilmesi için bu değerin gönderilmesi gerekmektedir. Kart sahibi "Öde ve Kartı Kaydet" ile işlemini yapması durumunda, kart kaydedilerek tranId değeri servis cevabında verilmektedir. | İsteğe Bağlı | 13813813813 |
PHP ile Hash oluşturma
$hashstr = $sx . $clientRefCode . $amount . $successUrl . $failUrl . $rnd . $merchantSecretKey;
$hashData = base64_encode(pack('H*',sha1($hashstr)));
.NET ile Hash oluşturma
String rnd = (DateTime.Now);
String str = sx + clientRefCode + amount + successUrl + failUrl + rnd + merchantSecretKey;
System.Security.Cryptography.SHA1 sha = new System.Security.Cryptography.SHA1CryptoServiceProvider();
byte[] bytes = System.Text.Encoding.UTF8.GetBytes(str);
byte[] hashingbytes = sha.ComputeHash(bytes);
String hashData = Convert.ToBase64String(hashingbytes);
Hash değerini bize diğer parametreler ile post ettiğinizde, biz de aynı değerleri hashliyoruz. Sizin gönderdiğiniz hash ile bizim ürettiğimiz hash bir birini tutar ise, request’in sizden geldiğini teyit ediyoruz.
<!doctype html>
<html>
<head>
<title>Sanal POS entegrasyonu örnek PHP sayfamız</title>
<meta charset="utf-8">
</head>
<body>
<?php
$sx="100000000|pGi2dXPOwdimyVtqUEYqb7WPqQqQ........."; // sx değeriniz size verilecektir
$merchantSecretKey="_YXMmaRPOK05Gzztl9lds"; // merchantSecretKey size özel gizli bilgidir, size verilecektir.
$successUrl="https://nkolaydepo.com/success-yeni-kk-provizyon-depo-prod-yeni"; // İşlem başarılı olduğunda sonuç parametrelerinin post edileceği sayfadır.
$failUrl="https://nkolaydepo.com/fail"; // İşlem başarısız olduğunda sonuç parametrelerinin post edileceği sayfadır.
$amount="1"; // karttan çekilecek tutar
$clientRefCode="2352345"; // İşleme ait referans numaranız
$use3D="true"; // İşlemi 3D secure olmaya zorlar
$rnd = date("d.m.Y H:i:s"); // işlem tarih ve saati
$agentCode="1236"; // varsa alt bayi kodu
$detail="false"; // True gönderilirse kredi kartı formunda ekstra bilgi alma alanları açılır. Ad soyad, Tc, Cep telefonu, Email, Açıklama, Adres
$transactionType="sales"; // sales ya da presales olarak gönderilir, satış ya da provizyondur.
$hashstr = $sx . $clientRefCode . $amount . $successUrl . $failUrl . $rnd . $merchantSecretKey;
$hashData = base64_encode(pack('H*',sha1($hashstr)));
?>
<form method="post" action="https://paynkolaytest.nkolayislem.com.tr/Vpos">
<input type="hidden" name="sx" value="<?php echo $sx ?>">
<input type="hidden" name="successUrl" value="<?php echo $successUrl ?>">
<input type="hidden" name="failUrl" value="<?php echo $failUrl ?>">
<input type="hidden" name="amount" value="<?php echo $amount ?>">
<input type="hidden" name="clientRefCode" value="<?php echo $clientRefCode ?>">
<input type="hidden" name="use3D" value="<?php echo $use3D ?>">
<input type="hidden" name="rnd" value="<?php echo $rnd ?>">
<input type="hidden" name="agentCode" value="<?php echo $agentCode ?>">
<input type="hidden" name="transactionType" value="<?php echo $transactionType ?>">
<input type="hidden" name="hashData" value="<?php echo $hashData ?>">
<input type="submit" value="Gönder" />
</form>
</body>
</html>
sx, merchantSecretKey değerleri size Pay N Kolay tarafından gönderilecektir.
POST edilen bilgiler doğru ise kredi kartı formu ekranı açılacaktır. Kredi kartı formuna kart bilgileri girildikten sonra, 3D işlem onayı gelecektir.
İhtiyacınız olan tüm parametreleri clientRefCode ile post edebilirsiniz. Örneğin: clientRefCode=”865988522| ikinci parametre | üçüncü parametre” daha sonra bunu kendi sunucunuzda ayrıştırabilirsiniz.
<%@ Page Language="C#" %>
<!doctype html>
<html>
<head>
<title>Sanal POS Örnek</title>
<meta http-equiv="Content-Language" content="tr">
<meta charset="utf-8">
</head>
<body>
<%
String sx="114488219|SjEH1wb6qoqWtN2X9/5Y6sVy/JxniIbR01EKWRcHxPl0iAjkadGNaNAEV5l6O3tjzcPEiFOO8OwCSb6dzo/fN/2zyv7sVbweqJvgKr7cWnMwPIgqipXBk+B7Z4bFqmeD1LlUgNMXdstufUNxmCHIfb3nT0NDrfScCxlQX8H1YYPvcNE+oTtci3fB+X/fpYec0Gu2JPAIzG74pQN07MmdHq+GSR73+RkAjMi0cP4pfjNf6C/0Igc6qcnTtYH9YIJIpRxySQ=="; // sx değeriniz size verilecektir
String merchantSecretKey="_YXMmaRPOK05Gzztl9lds"; // merchantSecretKey değeriniz size verilecektir, size özel gizli bilgidir
String successUrl="https://nkolaydepo.com/success-yeni-kk-provizyon-depo-prod-yeni"; // İşlem başarılı olduğunda sonuç parametrelerinin post edileceği sayfadır.
String failUrl="https://nkolaydepo.com/fail"; // İşlem başarısız olduğunda sonuç parametrelerinin post edileceği sayfadır.
String amount="1"; // karttan çekilecek tutar
String clientRefCode="2352345"; // İşleme ait referans numaranız
String use3D="true"; // İşlemi 3D secure yapmaya zorlar
String rnd = DateTime.Now.ToString("dd.MM.yyyy H:mm:ss"); // işlem tarih ve saati
String agentCode="1236"; // varsa alt bayi kodu
String detail="false"; // True gönderilirse kredi kartı formunda ekstra bilgi alma alanları açılır. Ad soyad, Tc, Cep telefonu, Email, Açıklama, Adres
String transactionType="sales"; // sales ya da presales olarak gönderilir, satış ya da provizyondur.
String str = sx + clientRefCode + amount + successUrl + failUrl + rnd + merchantSecretKey ;
System.Security.Cryptography.SHA1 sha = new System.Security.Cryptography.SHA1CryptoServiceProvider();
byte[] bytes = System.Text.Encoding.UTF8.GetBytes(str);
byte[] hashingbytes = sha.ComputeHash(bytes);
String hashData = Convert.ToBase64String(hashingbytes);
%>
<div>
<form method="post" action="https://paynkolaytest.nkolayislem.com.tr/Vpos">
<input type="hidden" name="sx" value="<%=sx%>">
<input type="hidden" name="successUrl" value="<%=successUrl%>">
<input type="hidden" name="failUrl" value="<%=failUrl%>">
<input type="hidden" name="amount" value="<%=amount%>">
<input type="hidden" name="clientRefCode" value="<%=clientRefCode%>">
<input type="hidden" name="use3D" value="<%=use3D%>">
<input type="hidden" name="rnd" value="<%=rnd%>">
<input type="hidden" name="agentCode" value="<%=agentCode%>">
<input type="hidden" name="detail" value="<%=detail%>">
<input type="hidden" name="transactionType" value="<%=transactionType%>">
<input type="hidden" name="hashData" value="<%=hashData%>">
<input type="submit" value="Gönder" />
</form>
</div>
</body>
</html>