VibeFox KOMOJU 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.

KOMOJU hesabı: gizli anahtara (sk_live_... ve test modu için sk_test_...) ihtiyacınız vardır; ayrıca KOMOJU panelinde oluşturulan bir webhook’un gizli jetonuna (bkz. Yapılandırma). Yayınlanabilir anahtar gerekmez. KOMOJU, mağazanızın webhook URL’sine erişebilmelidir.

Sepet para birimi: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD veya VND. Diğer para birimlerindeki sepetler için ödeme yöntemi gizlenir.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek 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 bittiğinde Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox KOMOJU Payment öğesini bulup Configure düğmesine tıklayın.

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

4. KOMOJU panelinde, Webhook URL bölümünde gösterilen URL ve olaylarla bir webhook ekleyin ve gizli jetonunu kopyalayın (bkz. Yapılandırma).

5. Canlı gizli anahtarı ve canlı webhook gizli jetonunu, test modu için de test anahtarlarını girin. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting KOMOJU payment ve KOMOJU payment on hold. PrestaShop yeni bir ödeme modülünü yalnızca o anda etkin olan ülkelere bağlar: daha sonra etkinleştirdiğiniz bir ülke, Payment > Preferences bölümünde modül için işaretlenmelidir. Orada para birimlerini ve müşteri gruplarını da sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox KOMOJU 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, test modu açıkken sayfa KOMOJU Sandbox Mode is enabled. gösterir. Geçerli modda gizli anahtar yoksa (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) veya gizli webhook jetonu yoksa (bu durumda KOMOJU bildirimleri reddedilir ve konbini ile banka havalesi ödemeleri hiçbir zaman onaylanmaz) ve KOMOJU mağazanın varsayılan para birimini desteklemiyorsa (bu durumda ödeme yöntemi o para birimindeki sepetler için gizlenir) sizi uyarır.

KOMOJU ödemesi

Enable/Disable: Enable KOMOJU Payment Gateway ödeme yöntemini açar veya kapatır. Varsayılan: kapalı.

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

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

Canlı API anahtarları

Anahtarları KOMOJU panelinde bulun: gizli anahtar Settings > API keys altında, webhook gizli jetonu Settings > Webhooks altında (önce oraya Webhook URL bölümünde gösterilen webhook URL’sini ekleyin).

Live Secret Key: KOMOJU canlı gizli anahtarınız. sk_live_ ile başlar.

Live Webhook Secret Token: canlı webhook’un gizli jetonu. Her bildirimin imzasını doğrulamak için kullanılır.

Test modu

KOMOJU, test ve canlı ödemeler için aynı API adresini kullanır: modu anahtar belirler. Ödemeler yapıldıkları modu korur; bu yüzden bir siparişin iadeleri ve durum kontrolleri her zaman o modun anahtarını kullanır.

Sandbox Mode: Enable test mode (use the test keys below, no real payments). Varsayılan: kapalı. Açıkken ödeme sayfası açıklamanın üstünde Test mode gösterir.

Sandbox Secret Key: KOMOJU test gizli anahtarınız. sk_test_ ile başlar.

Sandbox Webhook Secret Token: test modundaki webhook’un gizli jetonu.

Kaydedilmiş anahtarlar ve jetonlar 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.

Kaydedilmiş gizli bilgileri temizle: bir anahtarı veya jetonu işaretleyip kaldırmak için Save düğmesine tıklayın. Boş alan kaydedilmiş değeri korur.

Webhook adresi

Webhook, mağazanıza ödemeler hakkında bilgi verir; buna gecikmeli konbini ve banka havalesi ödemeleri de dahildir. KOMOJU panelinde Settings > Webhooks altında, bu bölümde gösterilen URL’yi hem canlı hem de test modu için ekleyin. Dostça URL’lerle şöyle görünür: https://your-shop/module/wcp_komoju_payment/webhook, belki /en/ gibi bir dil kodu ile. URL’yi ayarların gösterdiği gibi birebir kopyalayın. Ardından her webhook’un gizli jetonunu Live Webhook Secret Token veya Sandbox Webhook Secret Token alanına kopyalayın.

Şu olayları seçin (bu bölümde de listelenmiştir):

Süresi dolan, iptal edilen ve başarısız olan olaylar siparişi yalnızca mevcut ödemesi için değiştirir; bu yüzden önceki bir denemenin ödemesi, başka bir yolla ödenmekte olan bir siparişi iptal edemez. Geçerli imzası olmayan webhook’lar reddedilir. İki gizli jetonun herhangi biriyle imzalanmış webhook’lar kabul edilir, ancak yalnızca aynı moddaki ödemeler için. Webhook olmadan kartla yapılan ödemeler müşteri mağazaya döndüğünde yine onaylanır, ancak konbini ve banka havalesi ödemeleri hiçbir zaman onaylanmaz.

Gelişmiş

Invoice Prefix: KOMOJU’ya gönderilen sipariş numaralarının ön eki, ardından sepet numarası gelir. Aynı KOMOJU hesabıyla birden çok mağaza kullanıyorsanız her mağaza için benzersiz yapın. Varsayılan: PS-.

Enable Logging: KOMOJU olaylarını ve API çağrılarını modül klasöründeki logs/komoju_p_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Anahtarlar ve müşteri verileri günlüğe yazılmaz. Hatalar ve uyarılar her zaman yazılır. Varsayılan: kapalı.

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

Delete data on uninstall: açıksa, modül kaldırıldığında ağ geçidi ayarları ve günlük silinir. Siparişler, KOMOJU işlemleri ve iadeleri ile sipariş durumları her zaman kalır; böylece eski siparişler yeniden kurulumdan sonra da onaylanabilir ve iade edilebilir. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak KOMOJU Payment) ve onaylar. Modül, sepet toplamı ve sepetin para birimiyle bir KOMOJU ödeme oturumu oluşturur ve müşteriyi KOMOJU ödeme sayfasına yönlendirir. E-posta, ad, fatura ve teslimat adresleri ile sipariş edilen ürünler KOMOJU’ya iletilir. Sayfa, sepetin diline göre Japonca, İngilizce veya Korece gösterilir (diğer diller için İngilizce). Müşteri orada bir ödeme yöntemi seçer. Sunulan yöntemler KOMOJU hesabınıza ve sepet para birimine bağlıdır. Bu noktada henüz bir sipariş yoktur.

Ödeme sonrası müşteri mağazanıza döner. Modül, ödemenin moduna ait anahtarla ödeme oturumunu KOMOJU API’sinden okur. Sipariş, KOMOJU onaylayana kadar ödenmiş olarak işaretlenmez: imzalı webhook ile veya müşteri döndüğünde oturumun okunmasıyla. Sipariş bundan sonra oluşturulur ve müşteri standart sipariş onay sayfasını görür; sayfada Your payment with KOMOJU has been received. yazar. O anda KOMOJU’ya ulaşılamazsa, Payment confirmation sayfasında We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. mesajı ve Check again düğmesi gösterilir.

Konbini ve banka havalesi ödemelerinde müşteri bir ödeme belgesi alır. Sipariş Awaiting KOMOJU payment durumunda oluşturulur ve onay sayfası müşteriye ödemeyi KOMOJU’nun talimatlarına göre tamamlamasını söyler (örneğin bir markette veya banka havalesiyle). Müşteri ödeyip KOMOJU webhook’u gönderdiğinde sipariş Payment accepted olur. Belge daha sonra süresi dolarsa veya ödeme başarısız olursa, onay sayfası Your KOMOJU payment was not completed. Please contact us about this order. gösterir.

Ödeme tamamlanmadıysa müşteri The payment was not completed. You can try again or choose another payment method. mesajıyla ödeme sayfasına döner. Sepet korunur. Toplam değişmediyse yeni deneme açık KOMOJU oturumunu yeniden kullanır. Eski toplamlı bir oturum KOMOJU’da iptal edilir; bu arada ödenmiş bir oturum yeni bir ödeme yerine siparişi oluşturur.

KOMOJU ödemeyi başlatamazsa müşteri ödeme sayfasında kısa bir mesajla kalır, örneğin KOMOJU could not accept this payment: nedeniyle birlikte, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. veya Payment error: Could not connect to KOMOJU. Please try again in a moment. Teknik neden günlüğe yazılır.

Sepetteki bir kupon ödeme ile onayı arasında geçerliliğini yitirirse PrestaShop kuponu siparişten kaldırır. Bu durumda sipariş, müşteri indirimli fiyatı ödediği için not ile KOMOJU payment on hold durumuna geçer.

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

Modülün sitenizde kart formu, kayıtlı kart veya abonelik yoktur. Ödeme yöntemlerini kısıtlamaz: bunlar KOMOJU sayfasında seçilir. Elle tahsilat işlemi yoktur: elle tahsilat için yetkilendirilen ödemeler KOMOJU panelinde tahsil edilmelidir ve sipariş o zamana kadar Awaiting KOMOJU payment durumunda kalır.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri KOMOJU’ya gönderildi ve henüz ödeme yapmadı ya da KOMOJU ödemeyi henüz onaylamadı. Yalnızca sepet vardır.

Payment accepted: KOMOJU ödemeyi onayladı. Ödeme, işlem kimliği olarak KOMOJU ödeme kimliğiyle kaydedilir; bir not ödeme kimliğini, ödeme yöntemini ve onay şeklini (webhook veya dönüş) gösterir.

Awaiting KOMOJU payment: bir konbini veya banka havalesi belgesi düzenlendi ve ödeme bekliyor ya da bir ödeme KOMOJU panelinde tahsil edilmeyi bekliyor.

KOMOJU payment on hold: KOMOJU, sipariş toplamından farklı bir tutar veya para birimi bildirdi (örneğin ödeme başladıktan sonra sepet değiştirildi), bir kupon kaldırıldı veya sipariş iptal edildikten sonra ödeme tahsil edildi. Not durumu açıklar. Siparişi kontrol edin ve işleyin ya da ödemeyi iade edin.

Canceled: ödeme belgesinin süresi doldu veya ödeme iptal edildi.

Payment error: mevcut bir siparişin ödemesi başarısız oldu.

Refunded: ödeme sipariş sayfasından veya KOMOJU panelinden tamamen iade edildi.

Zaten ödenmiş bir sipariş için ikinci bir ödeme tahsil edilirse sipariş değişmez. Bir not, eğer bu bir mükerrer ödemeyse KOMOJU panelinde iade etmenizi ister. İade edilmiş siparişler asla yeniden açılmaz.

KOMOJU ödeme bloğu

Sipariş sayfasında, KOMOJU ödeme kimliğiyle (KOMOJU panelindeki ödemeye bağlantılı) ödeme yöntemi, oturum, KOMOJU’daki sipariş numarası, durum, ödenen tutar ve iade edilen tutar, test ödemeleri için Test mode rozeti, iade geçmişi ve siparişin KOMOJU notes bölümü gösterilen bir KOMOJU payment bloğu bulunur.

İadeler

KOMOJU payment bloğuna tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via KOMOJU düğmesine tıklayın. Refund this amount through KOMOJU? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir. İadeler, KOMOJU’nun gerçekte tahsil ettiği tutarla sınırlıdır; bu yüzden tutar uyuşmazlığından sonra sipariş toplamına değil, müşterinin ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı modun anahtarıyla gönderilir; bu nedenle o modun gizli anahtarı tanımlı olmalıdır. Modül önce KOMOJU’da ödemeyi kontrol eder ve hâlâ iade edilebilir tutarı aşan iadeleri reddeder. KOMOJU bir ödemeyi otomatik iade edemezse (örneğin konbini gibi bazı yöntemler müşterinin banka bilgilerini gerektirir), KOMOJU’nun hata mesajı gösterilir ve hiçbir şey kaydedilmez: bu tür iadeleri KOMOJU panelinde yapın. Bir iade, ancak KOMOJU onayladığında tamamlanmış sayılır. Başarılı bir iade, iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. İadeler, KOMOJU ödemeyi tahsil ettikten sonra kullanılabilir.

KOMOJU’nun başka bir para birimine çevirdiği ödemeler için (örneğin EUR sepet için JPY cinsinden konbini), PrestaShop’tan yalnızca tam iade yapılabilir. Kısmi iadeleri KOMOJU panelinde yapın.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri KOMOJU üzerinden para geri göndermez.

KOMOJU panelinde yapılan iadeler webhook ile gelir ve bir notla iade geçmişine eklenir. Tüm ödeme iade edildiğinde sipariş Refunded durumuna getirilir. Başka bir para birimine çevrilmiş ödemeler için panelde yapılan kısmi iadeler yalnızca siparişe not edilir: eşleşen tutarı PrestaShop’ta elle kaydedin (kredi notu).

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox KOMOJU Payment lisans bloğu, Modules > Module Manager > VibeFox KOMOJU Payment > 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 son tarih 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-komoju satırı ile 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 tarihli License expired on. Mağaza adresi değiştikten veya hesabınızda bir alan adı yuvasını boşalttıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa modül, son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: çok mağazalı bir kurulumda da ana mağazanın alan adında. 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 KOMOJU, ö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 yüzden ödeme yöntemi sizin için de gizlenir: modülü anahtar satın almadan önce ayarlayabilirsiniz, 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ın süresi dolduğunda 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 job gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

KOMOJU ö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 gizli anahtar bulunduğunu kontrol edin: test modunda Sandbox Secret Key, canlı modda Live Secret Key. Sepet para birimi KOMOJU tarafından desteklenmelidir. Ayarlar sayfası eksik bir şey olduğunda uyarı gösterir. Payment > Preferences bölümünde modülün sepet para birimi, müşterinin ülkesi ve müşteri grubu için izinli olduğunu kontrol edin.

Ödeme geçti ama sipariş oluşmadı: webhook çalışmıyor. KOMOJU panelinde kullandığınız mod için webhook’un var olduğunu, URL’sinin Webhook URL bölümünde gösterilenle birebir aynı olduğunu ve olayların seçili olduğunu kontrol edin. Gizli jetonunun doğru alanda olduğunu (Live Webhook Secret Token veya Sandbox Webhook Secret Token) kontrol edin ve modül sayfasındaki Log alanına bakın. Kartla yapılan ödemeler müşteri mağazaya döndüğünde de onaylanır, ancak konbini ve banka havalesi ödemeleri yalnızca webhook ile onaylanır.

Webhook yanıtı Failed to verify KOMOJU webhook signature.: gizli jeton eksik veya başka bir webhook’a ait. KOMOJU bildirimi yeniden dener.

Webhook yanıtı Mode mismatch, ignored.: webhook, ödemenin yapıldığı moddan farklı modun gizli jetonuyla imzalanmış. Canlı ve test modları için ayrı webhook’lar ve jetonlar kullanın, bunların karıştırılmadığını kontrol edin.

Webhook yanıtı Order is busy, retry later. veya Temporary error, retry later.: sipariş başka bir istek tarafından güncelleniyordu, sipariş o anda oluşturulamadı (örneğin modül devre dışı) veya ödeme kontrol edilemedi. KOMOJU bildirimi yeniden dener. Neden günlükte yazar.

Webhook adresi tarayıcıda hata gösteriyor: bu normaldir. URL yalnızca KOMOJU’dan gelen imzalı istekleri kabul eder.

Sipariş KOMOJU payment on hold veya Awaiting KOMOJU payment durumunda: sipariş bloğundaki KOMOJU notes notlarını okuyun. Bir belge ödeme bekliyor, bir ödeme KOMOJU panelinde tahsil edilmeyi bekliyor, tutar veya para birimi uyuşmadı, bir kupon kaldırıldı ya da ödeme siparişin iptalinden sonra geldi.

İade başarısız: mesajı okuyun. Ödemenin yapıldığı modun gizli anahtarı eksik olabilir, ödeme otomatik iade edilemiyor olabilir (KOMOJU panelinde iade edin), KOMOJU ödemeyi yapılandırılmış anahtarla tanımıyor olabilir veya dönüştürülmüş bir ödeme için yalnızca tam iade mümkün olabilir.

Geliştiriciler, para birimleri listesini actionKomojuPSupportedCurrencies kancasıyla, ödeme oturumunu (örneğin ödeme yöntemlerini) ise actionKomojuPSessionParams kancasıyla değiştirebilir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox KOMOJU 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 ağ geçidi ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. KOMOJU işlemleri ve iadeleri ile Awaiting KOMOJU payment ve KOMOJU payment on hold sipariş durumları her zaman korunur; böylece eski siparişler yeniden kurulumdan sonra da onaylanabilir ve iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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