VibeFox Kushki for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

PHP: 8.0 veya üzeri. Modül, eski PHP sürümlerine kurulmayı reddeder.

Para birimi: USD (Ekvador) veya COP (Kolombiya). Diğer para birimlerindeki sepetler için ödeme yöntemi ödeme sayfasında gizlenir.

HTTPS: Kushki, canlı modda ödeme sayfasının HTTPS üzerinden sunulmasını gerektirir.

Kushki hesabı: Kushki test (UAT) hesabınızın ve üretim hesabınızın Public ve Private Merchant ID'lerine ihtiyacınız var. Bunlar Kushki Console'da Developers > Credentials altında bulunur. İsteğe bağlı webhook için her hesabın webhook imza anahtarına da ihtiyacınız var (bkz. Yapılandırma).

VibeFox license key: vibefox.net üzerinden satın alınır. Bir anahtar bir alan adında çalışır.

Kurulum

1. Yönetim panelinde Modules > Module Manager bölümüne gidin ve Upload a module düğmesine tıklayın. Modülün ZIP dosyasını seçin.

2. Yükleme tamamlandığında Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox Kushki Payment modülünü bulup Configure düğmesine tıklayın.

3. Configure sayfasının üstündeki lisans bloğunda License key alanına VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

4. Test Public ve Private Merchant ID'lerini girin ve Test mode seçeneğini açık bırakın. İsteğe bağlı olarak Kushki Console'da webhook'u ayarlayın ve imza anahtarını yapıştırın (bkz. Yapılandırma).

5. Enable / Disable seçeneğini açın, Save düğmesine tıklayın ve bir test siparişi verin. Hazır olduğunuzda canlı Merchant ID'lerini (ve canlı webhook imzasını) girin ve Test mode seçeneğini kapatın.

Kurulumda modül Kushki payment on hold sipariş durumunu oluşturur. PrestaShop, yeni ödeme modülünü mağazanızın para birimlerine, ülkelerine ve müşteri gruplarına atar. Payment > Preferences bölümünde modülün USD veya COP için ve Ekvador veya Kolombiya için izinli olduğunu kontrol edin.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Kushki Payment > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Alanların üstünde sayfa; ödeme yöntemi etkin olmasına rağmen geçerli modun Merchant ID'leri eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir), mağazanızın varsayılan para birimi USD veya COP değilse, canlı mod HTTPS olmadan kullanılıyorsa ve geçerli modda webhook imzası yoksa sizi uyarır. Test modu açıkken Test modu açık: Kushki test ortamı kullanılır, gerçek para tahsil edilmez. mesajını gösterir. Ödeme yöntemi etkinken ancak geçerli modun Merchant ID'leri olmadan kaydederseniz ayarlar kaydedilir ve bir mesaj bunları girmenizi hatırlatır. Kayıt sırasında ID'lerin etrafındaki boşluklar silinir.

Kushki

Enable / Disable: Enable Kushki card payments ödeme yöntemini açar veya kapatır. Varsayılan: kapalı.

Title: müşterilerin ödeme sayfasında gördüğü ödeme yöntemi adı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Credit / debit card (Kushki). Zorunlu.

Description: ödeme sayfasında kart formunun üstünde gösterilen metin. Varsayılan: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

API kimlik bilgileri

Public ve Private Merchant ID'lerini Kushki Console'dan (Developers > Credentials) kopyalayın. Test (UAT) ve üretim hesaplarının ID'leri farklıdır. Test modu yalnızca test ID'lerini, canlı mod yalnızca canlı ID'lerini kullanır.

Test mode: Kushki test (UAT) ortamını kullanır: test Merchant ID'leri, test kart formu ve test API birlikte kullanılır. Gerçek para tahsil edilmez ve ödeme sayfasında TEST MODE rozeti gösterilir. Varsayılan: açık. Gerçek ödeme almak için kapatın. İadeler her zaman ödemenin yapıldığı ortama gönderilir.

Test Public Merchant ID: Kushki test hesabınızın Public Merchant ID'si. Kart formunu yükler.

Test Private Merchant ID: Kushki test hesabınızın Private Merchant ID'si. Sunucuda tahsilat ve iadeler için kullanılır.

Live Public Merchant ID: Kushki üretim hesabınızın Public Merchant ID'si.

Live Private Merchant ID: Kushki üretim hesabınızın Private Merchant ID'si. Gizli tutun.

Kaydedilmiş Private Merchant ID'leri ve webhook imzaları bir daha gösterilmez. Alan boş kalır ve Kayıtlı — korumak için boş bırakın. mesajını gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Webhook (önerilir)

Ödemeler Kushki API yanıtıyla anında onaylanır, bu nedenle webhook zorunlu değildir. Ek olarak, yanıtı kaybolan (örneğin zaman aşımı nedeniyle) bir ödeme için siparişi oluşturur ve Kushki Console'da yapılan iptal ve iadeleri bildirir. Kushki Console'da (Webhooks) kart ödemeleri için Webhook URL altında gösterilen URL'yi ekleyin. Dostu URL'lerle şu biçimde görünür: https://your-shop/module/wcp_kushki_payment/webhook; başında /es/ gibi bir dil kodu da olabilir. URL'yi ayarların gösterdiği şekilde tam olarak kopyalayın. Bunu hem test hesabı hem de üretim hesabı için yapın.

Modül şu kart bildirimlerini işler:

Test webhook signature: Kushki test hesabının webhook imza anahtarı (Console > Webhooks).

Live webhook signature: Kushki üretim hesabının webhook imza anahtarı.

Clear saved secrets: bir Private Merchant ID'yi veya webhook imzasını işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş alan kayıtlı değeri korur.

Geçerli imzası olmayan webhook'lar reddedilir. Bir bildirim, ödemenin yapıldığı modun anahtarıyla imzalanmış olmalıdır; bu nedenle bir test bildirimi asla gerçek bir ödemeyi onaylamaz. İmza anahtarı yoksa tüm webhook bildirimleri reddedilir, ancak ödemeler çalışmaya devam eder, çünkü API yanıtıyla onaylanırlar.

Gelişmiş

Debug log: Kushki isteklerini ve webhook'larını modül klasöründeki logs/kushki_p_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar her zaman kaydedilir. Günlükler hiçbir zaman Merchant ID'leri, kart jetonlarını veya müşteri e-postalarını içermez. Varsayılan: kapalı.

Log: günlüğün boyutunu ve son kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Delete data on uninstall: açıkken modül kaldırıldığında ayarlar ve günlükler silinir. Kushki ödeme kayıtları (tahsilatlar ve iadeler) ile Kushki payment on hold sipariş durumu her zaman korunur; böylece eski siparişler yeniden kurulumdan sonra da iade edilebilir. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Credit / debit card (Kushki)). Altında, sepet para biriminde sepet toplamıyla birlikte Kushki kart formu görünür. Müşteri kartını girer, Kushki formu sunuyorsa taksit seçer ve Kushki formunun içindeki ödeme düğmesine basar.

PrestaShop Place order düğmesi, satış koşullarını içerdiği için görünür kalır. Koşullar zaten kabul edilmişse ödeme, Kushki ödeme düğmesinden sonra otomatik olarak gönderilir. Aksi takdirde müşteri Kartınız Kushki tarafından kabul edildi. Satış koşullarını kabul edin ve ödemek için "Place order" düğmesine basın. mesajını görür. Müşteri Kushki formunu kullanmadan Place order düğmesine basarsa Lütfen kart bilgilerinizi Kushki formuna girin ve formun ödeme düğmesine basın. mesajı gösterilir.

Ardından mağazanız kartı sunucuda tahsil eder. Sipariş yalnızca Kushki bir fiş numarasıyla onayladıktan sonra ödenmiş olarak işaretlenir. Sipariş daha sonra oluşturulur ve müşteri Kart ödemeniz alındı. mesajını içeren standart sipariş onay sayfasını görür. Kushki onaylanmış bir tutar veya para birimi bildirirse bunlar sepetle karşılaştırılır. Bekleyen bir sipariş Ödemeniz inceleniyor. İnceleme tamamlanır tamamlanmaz siparişinizi güncelleyeceğiz. mesajını gösterir.

Kart reddedilirse sipariş oluşturulmaz ve müşteri, Ödemeniz reddedildi mesajı ve Kushki'nin verdiği nedenle ödeme adımına döner; başka bir kart deneyebilir. Ağ, anahtar veya sunucu sorunlarında müşteri Ödeme şu anda işlenemedi. Lütfen birkaç dakika sonra tekrar deneyin veya başka bir ödeme yöntemi seçin. mesajını görür. Teknik neden günlüğe yazılır. Bir ödeme işlenirken ikinci kez tıklamak Bu sipariş için bir ödeme zaten işleniyor. Lütfen bir an bekleyin ve sipariş durumunuzu kontrol edin. mesajını gösterir.

Kushki yanıtı kaybolursa (örneğin zaman aşımında) müşteri genel mesajı görür, ancak tahsilat denemesi korunur. İmzalı webhook onaylanmış tahsilatı bildirdiğinde sipariş oluşturulur. Zaten siparişi olan bir sepet ya da siparişi henüz oluşturulmamış onaylanmış bir tahsilat asla yeniden tahsil edilmez: müşteri o siparişin onayını görür. Bir webhook gelmeden önce müşteri tekrar öderse bu yeni bir tahsilattır; ilk tahsilatın geç onayı yalnızca olası bir çift tahsilat hakkında bir not ekler.

Webhook, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez. 3-D Secure, dolandırıcılık kuralları ve sunulan taksitler Kushki Console'da ayarlanır.

Modül yalnızca tek adımlı kart ödemelerini kabul eder. Kısmi iade, kayıtlı kart veya abonelik desteği, nakit, banka havalesi (PSE) veya yönlendirmeli banka kartı ödemesi ve ayrı yetkilendirme ile tahsilat desteği yoktur.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri ödeme yapmadı, kart reddedildi veya Kushki yanıtı kayboldu ve webhook henüz gelmedi. Yalnızca sepet vardır.

Payment accepted: Kushki tahsilatı onayladı (API yanıtıyla veya webhook ile). Ödeme, Kushki işlem referansı (veya fiş numarası) işlem kimliği olarak kaydedilir. Bir not modu, Kushki fiş numarasını ve referansı gösterir.

Kushki payment on hold: Kushki fiş numarası olmadan başarı döndürdü, sepetten farklı bir tutar veya para birimi bildirdi ya da ödeme sırasında sepet değiştirildi. Not bunu açıklar. Kushki Console'da işlemi kontrol edin ve siparişi tamamlayın veya ödemeyi iade edin. Daha sonra fiş numarası ve eşleşen tutarla gelen imzalı bir onay siparişi Payment accepted durumuna getirir.

Payment error: webhook, bekleyen bir siparişin tahsilatının reddedildiğini bildirdi.

Refunded: ödeme modül aracılığıyla iade edildi.

Kushki, zaten ödenmiş, iptal edilmiş veya iade edilmiş bir sipariş için başka bir onaylanmış tahsilat bildirirse sipariş değişmez. Bir not, çift tahsilatı kontrol edip Kushki Console'da iade etmenizi ister. Canlı bir ödeme için test ortamından gelen bir webhook (veya tersi) bir notla yok sayılır.

Kushki ödeme bloğu

Sipariş sayfasında fiş numarası, işlem referansı, ortam (test ödemeleri için Test rozetiyle), tahsilatın durumu, tahsil edilen tutar ve sipariş toplamı, iade formu, iade geçmişi ve siparişin Kushki notes bölümünü içeren bir Kushki payment bloğu gösterilir.

İadeler

Kushki tahsilatın tamamını iade eder, bu nedenle yalnızca tam iadeler mümkündür. Kushki payment bloğunda Kushki'nin tahsil ettiği tutar zaten doldurulmuştur. İsteğe bağlı olarak bir neden girin ve Refund via Kushki düğmesine tıklayın, ardından Tüm ödeme Kushki üzerinden iade edilsin mi? Bu işlem geri alınamaz. sorusunu onaylayın. Siparişleri düzenleme yetkisine sahip olmanız gerekir. Diğer tutarlar için modül, tutarla birlikte Kushki yalnızca tüm ödemeyi iade eder. Tahsil edilen tüm tutarı girin mesajını gösterir ve hiçbir şey gönderilmez. İade, Kushki'nin tahsil ettiği tutar ve para biriminde yapılır; dolayısıyla tutar uyuşmazlığı olduğunda müşteri sipariş toplamını değil, gerçekten tahsil edilen tutarı geri alır. Bir ödeme yalnızca bir kez iade edilebilir.

İade, ödemenin yapıldığı modda (test veya canlı) gönderilir; bu nedenle o modun Private Merchant ID'si girilmiş olmalıdır. Kushki iadeyi kabul etmezse blok, Kushki kodu ve mesajıyla birlikte Kushki iadesi başarısız mesajını gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, iade geçmişine ve Kushki iade fişiyle birlikte notlara eklenir ve sipariş Refunded durumuna alınır. İadeler, fiş numarası olan onaylanmış bir Kushki tahsilatı gerektirir.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Kushki üzerinden para geri göndermez. Kushki Console'da yapılan iptaller ve iadeler webhook ile gelir ve notlara eklenir. Sipariş durumu otomatik olarak değişmez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Kushki Payment lisans bloğu, Modules > Module Manager > VibeFox Kushki Payment > Configure sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu son tarih ve alan adınız) ve şu düğmeleri gösterir: durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu mağazadan kaldırmak için Remove key. Bunların altında Product: presta-payment-kushki satırı ve vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure izni olan çalışanlar değiştirebilir. Bloğun metinleri yönetim paneli dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini gösterir; örneğin Key not found, This key belongs to another product, Domain limit reached veya License expired on ve bir tarih. Mağaza adresi değiştikten sonra veya hesabınızda bir alan adı yuvasını serbest bıraktıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamıyorsa modül son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: ana mağazanın alan adında, çoklu mağaza kurulumunda da. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızda serbest bırakın.

Etkin bir anahtar olmadan Kushki ödeme sayfasında müşterilere gösterilmez. Yine de bir ödeme başlatılırsa müşteri This payment method is not available. Please choose another one. mesajını görür. PrestaShop vitrini yönetim paneline giriş yaptığınızı bilmez, bu nedenle ödeme yöntemi sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme sayfasında test edemezsiniz. Modules > Module Manager bölümünde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Yönetim panelinde çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, ardından haftada bir kez. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

Kushki ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu ve geçerli modda her iki Merchant ID'nin de bulunduğunu kontrol edin: test modunda test ID'leri, canlı modda canlı ID'leri. Sepet para biriminin USD veya COP olduğunu kontrol edin. Payment > Preferences bölümünde modülün sepet para birimi, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin. Ayarlar sayfası, ID'ler eksik olduğunda uyarı gösterir.

Ödeme başarılı oldu, ancak sipariş oluşturulmadı: Kushki API yanıtı, örneğin zaman aşımı nedeniyle kaybolmuştur. Webhook bu tür ödemeler için siparişi oluşturur. Kushki Console'da webhook URL'sinin Webhook URL altında gösterilenle tam olarak aynı olduğunu, kullandığınız modun hesabı için olduğunu ve o hesabın imza anahtarının ilgili alanda (Test webhook signature veya Live webhook signature) bulunduğunu kontrol edin. Ödenen tutar ve para birimi olmadan onaylanmış bir tahsilat, siparişi Kushki payment on hold durumunda oluşturur.

Webhook yanıtı Webhook signature not configured: iki webhook imzasının da ayarlanmadığını gösterir. İmza anahtarını ayarlara yapıştırın.

Webhook yanıtı Invalid signature: imza anahtarı başka bir hesaba veya moda aittir ya da bildirim yolda değiştirilmiştir.

Webhook yanıtı Order mismatch: bildirim bu sepetin bir tahsilatına ait değildir (yanlış deneme anahtarı veya işlem). Hiçbir şey değişmez.

Webhook yanıtı Busy, retry later: sipariş aynı anda başka bir istek tarafından işleniyordu veya sipariş oluşturulamadı (örneğin modül devre dışıdır). Kushki bildirimi yeniden gönderebilir. Hatalar her zaman günlüğe yazılır.

Webhook URL'si tarayıcıda yalnızca POST gösteriyor: bu normaldir. URL yalnızca Kushki'den gelen bildirimleri kabul eder.

Kart formu yüklenmiyor: müşteri Kushki kart formu yüklenemedi. Lütfen sayfayı yenileyin veya başka bir ödeme yöntemi seçin. mesajını görür. Geçerli modun Public Merchant ID'sini kontrol edin.

Müşteri şu mesajı görüyor: Bu ödeme seçeneği bu mağazada kullanılamıyor. Lütfen kartla ödeyin.: Kushki formunda kart olmayan bir ödeme seçeneği seçildi. Modül yalnızca kartları tahsil eder.

Müşteri ödeme yaparken bir hata görüyor: Debug log seçeneğini açın ve modül sayfasındaki Log alanına bakın. Yanlış veya eksik bir Private Merchant ID, ödemenin işlenemediğine dair genel mesajı verir.

Müşteri Ödemeniz alındı, ancak sipariş otomatik olarak tamamlanamadı mesajını görüyor: Kushki tahsilatı onayladı, ancak PrestaShop siparişi oluşturamadı. Günlükte neden yazılıdır. Aynı sepetin bir sonraki ödeme denemesi, yeni bir tahsilat yapmadan siparişi oluşturur.

İade, mod hakkında bir mesajla başarısız oluyor: ödeme test veya canlı modda yapıldı ve o modun Private Merchant ID'si girilmemiş. Girin ve yeniden deneyin.

İade sunulmuyor ve «Bu sipariş için Kushki fiş numarası bulunamadı» mesajı görünüyor: siparişin onaylanmış bir Kushki tahsilatı yok. Kushki Console'da iade edin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Kushki Payment yanındaki menüyü açın ve Uninstall seçeneğini seçin. Bu modülün lisans anahtarı ve lisans durumu her zaman kaldırılır. Delete data on uninstall açıksa ayarlar ve günlükler silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Kushki ödeme kayıtları (tahsilatlar ve iadeler) ile Kushki payment on hold sipariş durumu her zaman saklanır; böylece daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını, Kushki fiş numaralarını ve işlem kimliklerini korur.

Kushki, ilgili sahibinin ticari markasıdır. Bu modül Kushki ile bağlantılı değildir ve Kushki tarafından onaylanmamıştır.