VibeFox Khipu for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

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

Para birimi: Şili pesosu (CLP), Arjantin pesosu (ARS) veya Peru solü (PEN). Diğer para birimlerindeki sepetler için ödeme yöntemi ödeme adımında gizlenir.

Khipu hesabı: Khipu tahsilat hesabınızın Receiver ID'sine («Id de cobrador»), API anahtarına ve gizli anahtarına (Secret key) ihtiyacınız var. Bunları Khipu hesabınızda, satıcı profilinde bulabilirsiniz (khipu.com/merchant/profile). Üçü de zorunludur: gizli anahtar olmadan hiçbir ödeme onaylanamaz. Khipu hesabında herhangi bir ayar yapmanız gerekmez.

Erişilebilir mağaza: Khipu, ödemeleri mağazanızı çağırarak onaylar; bu nedenle bildirim URL'si parola koruması olmadan ve Khipu'yu engelleyen bir güvenlik duvarı olmadan internetten erişilebilir olmalıdır. Mağazanın bakım modu bunu engellemez.

VibeFox lisans anahtarı: 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 Khipu Gateway öğesini 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. Khipu tahsilat hesabınızın Receiver ID, API key ve Secret key bilgilerini girin (bkz. Yapılandırma).

5. Enable / Disable seçeneğini açın ve Save düğmesine tıklayın. Önce test etmek için bir Khipu geliştirici hesabının anahtarlarını kullanın, ardından bunları canlı hesabınızın anahtarlarıyla değiştirin.

Kurulum sırasında modül Khipu payment on hold sipariş durumunu oluşturur. PrestaShop, yeni ödeme modülünü tüm para birimleri, ülkeler ve müşteri grupları için varsayılan olarak etkinleştirir. Bunları Payment > Preferences bölümünden sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Khipu Gateway > 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; Receiver ID, API key veya Secret key eksik olduğunda (bu durumda Khipu ödeme adımında sunulmaz) ve mağazanın varsayılan para birimi Khipu tarafından desteklenmediğinde sizi uyarır.

Khipu

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

Title: müşterilerin ödeme adımında gördüğü ödeme yöntemi adı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Khipu. Zorunlu.

Description: ödeme adımında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay by bank transfer with Khipu.

Khipu hesabı

Receiver ID, API key ve Secret key bilgilerini Khipu tahsilat hesabınızdan (khipu.com/merchant/profile) kopyalayın. Khipu'nun ayrı bir test sunucusu yoktur ve modülde test modu anahtarı bulunmaz. Test etmek için bir geliştirici tahsilat hesabının («desarrollo») anahtarlarını kullanın: bu hesap DemoBank test bankası üzerinden öder ve gerçek para hareket etmez. Canlıya geçtiğinizde canlı tahsilat hesabınızın anahtarlarına geçin.

Receiver ID: Khipu tahsilatçı («cobrador») kimliğiniz. Diğer Khipu hesaplarının ödemeleri reddedilir.

API key: ödeme oluşturmak ve her ödemeyi Khipu ile doğrulamak için kullanılır.

Secret key: Khipu ödeme bildirimlerinin imzasını (HMAC-SHA256) doğrulamak için kullanılır. Bu anahtar olmadan hiçbir ödeme onaylanamaz.

Kaydedilmiş anahtarlar bir daha gösterilmez. Alan boş kalır ve Saved — leave empty to keep it. ifadesini gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Clear saved secrets: API key veya Secret key seçeneğini işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödeme bildirimleri

Notification URL: Khipu, ödemeleri burada gösterilen URL'yi çağırarak onaylar. Dostça URL'ler etkinse şöyle görünür: https://your-shop/module/wcp_khipu_gateway/webhook, başına bir dil kodu eklenmiş olabilir. URL her ödemeyle otomatik olarak gönderilir; bu nedenle Khipu hesabınızda yapılandırılacak bir şey yoktur, ancak URL internetten erişilebilir olmalıdır.

Her bildirim, Secret key anahtarınızla oluşturulmuş geçerli bir imza taşımalıdır. Geçerli imzası olmayan bildirimler reddedilir. Modül, bildirimin içeriğine asla güvenmez: Khipu'dan ödeme durumunu sorar ve Khipu'nun bildirdiğine göre işlem yapar:

Status after payment: Khipu ödemeyi onayladığında siparişin alacağı durum. Durum hemen, tek bir durum değişikliğiyle ayarlanır.

Gelişmiş

Debug log: API çağrılarını ve bildirimleri modül klasöründeki logs/wc_khp_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar anahtar kapalıyken bile her zaman kaydedilir. Anahtarlar ve ödeyen verileri asla yazılmaz. Varsayılan: kapalı.

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

Delete data on uninstall: açık olduğunda modül kaldırıldığında ağ geçidi ayarları ve günlük silinir. Sipariş verileri (siparişlerin Khipu ödeme kimlikleri) her zaman korunur. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini (varsayılan olarak Khipu), açıklamasıyla birlikte seçer ve siparişi onaylar. Modül, sepet tutarı için sepet para biriminde bir Khipu ödemesi oluşturur ve müşteriyi Khipu ödeme sayfasına yönlendirir. Khipu'da ödeme, sepet numarası ve mağaza adıyla birlikte ürün listesiyle Order # olarak görünür. Müşterinin e-posta adresi geçerliyse Khipu'ya iletilir. Khipu sayfasında müşteri, kendi bankasından banka havalesiyle öder. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Khipu onayladığında ödenmiş olarak işaretlenir: imzalı bildirimle veya müşteri döndüğünde Khipu'ya yapılan bir durum sorgusuyla. Dönüşün kendisi hiçbir şeyi ödenmiş olarak işaretlemez. Sipariş oluşturulduktan sonra müşteri standart sipariş onay sayfasını görür. Banka havaleyi hâlâ doğruluyorsa veya Khipu'ya ulaşılamıyorsa, Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. metnini ve Check again ile Back to checkout düğmelerini içeren bir Payment confirmation sayfası gösterilir. Sepetin son Khipu ödemesi siparişle eşleştirilemiyorsa (örneğin başka bir Receiver ID'ye aitse), müşteri We could not match this payment to an order. If you paid, please contact us. mesajıyla ödeme adımına döner.

Müşteri ödeme yapmadan Khipu sayfasından ayrılırsa veya ödeme tamamlanmamışsa, The Khipu payment was not completed. You can try again or choose another payment method. mesajıyla ödeme adımına döner. Sepet korunur. Yeni bir deneme, önceki ödenmemiş Khipu ödemesini siler; böylece eski bağlantı üzerinden artık ödeme yapılamaz. Khipu önceki ödemeyi zaten aldıysa sipariş oluşturulur ve yeni bir ödeme yapılmaz. Önceki havale hâlâ doğrulanıyorsa müşteri Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. mesajını görür.

Khipu ödemeyi oluşturamazsa müşteri kısa bir mesajla ödeme adımında kalır; örneğin Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. veya Khipu is temporarily unavailable. Please try again in a few minutes. Ayrıntılar günlüğe yazılır.

Bildirim, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez.

Modül yalnızca tek seferlik banka havalesi ödemelerini kabul eder. İadeler PrestaShop'tan Khipu'ya gönderilmez; modülde abonelik, kayıtlı ödeme yöntemi veya ön yetkilendirme yoktur. Ödenmemiş ödemeler bir stok rezervasyonuna bağlanmaz.

Siparişler

Sipariş durumları

No order yet: müşteri Khipu'ya yönlendirildi ve ödeme yapmadı ya da Khipu havaleyi henüz onaylamadı. Yalnızca sepet mevcut.

Payment accepted or Delivered: Khipu ödemeyi onayladı. Durum, Status after payment ayarını izler. Ödeme, Khipu ödeme kimliği işlem kimliği olarak kaydedilir ve bir not Khipu payment verified. Payment ID: ile ödeme kimliğini ve tutarı gösterir.

Khipu payment on hold: Khipu, tutarı veya para birimi siparişle uyuşmayan bir ödemeyi onayladı (örneğin ödeme başladıktan sonra sepet değiştirildi) ya da ödeme siparişin iptal edilmesinden sonra geldi. Gerçekte alınan tutar siparişe kaydedilir (para birimi farklıysa kaydedilmez) ve bir not bunu açıklar. Ödemeyi Khipu hesabınızda kontrol edin, ardından siparişi tamamlayın veya müşteriye iade yapın. Aynı sepet için doğru tutarda sonraki bir ödeme gelirse sipariş ödenmiş duruma geçer.

Zaten ödenmiş veya ödemeden sonra kapatılmış bir sipariş için ödeme gelirse sipariş değiştirilmez. Bir not, bunun ikinci bir ödeme olması durumunda müşteriye iade yapmanızı ister. Khipu ödenmiş bir ödemeyi geri alınmış olarak bildirirse sipariş bir not alır ve durumu değişmez.

Khipu ödeme bloğu

Sipariş sayfasında, siparişin sepetine ait Khipu ödeme denemelerini (tarih, tutar, Khipu ödeme kimliği, Khipu durumu ve sonucu) gösteren bir Khipu payment bloğu, sipariş Khipu payment on hold durumundayken bir Manual review uyarısı ve siparişin Khipu notes notları yer alır. Blok salt okunurdur.

İadeler

İadeler PrestaShop'tan Khipu'ya gönderilmez, çünkü Khipu API'si üzerinden iade sunmaz. Müşteriye Khipu hesabınızdan veya banka havalesiyle iade yapın, ardından iadeyi PrestaShop'ta elle kaydedin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Khipu Gateway lisans bloğu, Modules > Module Manager > VibeFox Khipu Gateway > Configure sayfasında ayarların üstünde ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskeli olarak, durumu (örneğin lisansın geçerli olduğu tarihi ve alan adınızı) ve Check now (durumu yeniden kontrol eder), Change key (başka bir anahtar girer) ve Remove key (anahtarı bu mağazadan kaldırır) düğmelerini gösterir. Bunların altında Product: presta-payment-khipu satırı ve Manage licenses and domains in your account bağlantısı bulunur; bağlantı vibefox.net hesabınızı açar. 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şılamazsa modül, bilinen son duruma göre çalışmaya devam eder.

Bir anahtar 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ızdan serbest bırakın.

Etkin bir anahtar olmadan Khipu, ödeme adımı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ü anahtar satın almadan önce kurabilirsiniz, ancak ödeme adımında test edemezsiniz. Modules > Module Manager sayfasında Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır.

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

Sorun giderme

Khipu ödeme adımında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu ve Receiver ID, API key ve Secret key alanlarının hepsinin girildiğini kontrol edin. Sepet para birimi CLP, ARS veya PEN olmalıdır. Eksik bir şey olduğunda ayarlar sayfası uyarı gösterir. 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.

Ödeme geçti ama sipariş oluşturulmadı: Khipu, havaleyi banka doğruladıktan sonra onaylar. Sipariş, Khipu bildirimi geldiğinde veya müşteri Check again düğmesine tıkladığında oluşturulur. Mağazanızın Notification URL alanında gösterilen URL'de internetten erişilebilir olduğunu kontrol edin (Khipu'yu engelleyen parola koruması ya da güvenlik duvarı olmadan) ve modül sayfasındaki Log alanına bakın.

Bildirim Secret key not configured yanıtı veriyor: Secret key boş. Girin. Khipu bildirimi yeniden gönderir.

Bildirim Invalid signature, Missing signature veya Malformed signature yanıtı veriyor: Secret key, kullandığınız anahtarların ait olduğu tahsilat hesabına ait değil veya istek Khipu'dan gelmedi.

Bildirim Order not found veya Payment does not belong to this order yanıtı veriyor: ödeme başka bir Receiver ID'ye veya başka bir sepete yapılmış. Receiver ID değerini kontrol edin.

Bildirim Payment not final yet veya Verification unavailable yanıtı veriyor: havale hâlâ doğrulanıyor veya Khipu'ya ulaşılamadı. Khipu bildirimi yeniden gönderir.

Bildirim Busy, retry later veya Order could not be created, retry later yanıtı veriyor: sipariş aynı anda başka bir istek tarafından onaylanıyordu veya sipariş oluşturulamadı (örneğin modül devre dışı). Khipu bildirimi yeniden gönderir. Nedeni günlükte yazar.

Sipariş Khipu payment on hold durumunda: Khipu payment bloğundaki notları okuyun. Tutar veya para birimi siparişle uyuşmadı ya da ödeme siparişin iptal edilmesinden sonra geldi.

Müşteri "Khipu payments are not available right now" mesajını görüyor: API key eksik veya yanlış. Khipu hesabınızdaki anahtarları kontrol edin.

Khipu hesabınız başka bir para birimini kabul ediyorsa, örneğin Khipu İspanya için EUR, geliştiriciler bunu actionWcpKhipuSupportedCurrencies hook'uyla ekleyebilir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Khipu Gateway 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 ağ geçidi ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Khipu ödeme denemeleri ve Khipu payment on hold sipariş durumu her zaman korunur. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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