VibeFox Yoco for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

PHP: 8.0 veya üzeri. Modül, daha eski PHP sürümlerinde kurulmaz.

Mağaza para birimi: Güney Afrika randı (ZAR). Yoco yalnızca ZAR kabul eder. Başka bir para biriminde ödeme yöntemi ödeme sayfasında gösterilmez. Sipariş toplamı en az R2,00 olmalıdır.

Yoco hesabı: çevrimiçi ödemeleri olan bir Yoco hesabı. Yoco Business Portal'da Selling Online > Payment Gateway altında bulunan gizli anahtarlar gerekir. Yalnızca gizli anahtarlar girilir. Webhook modül tarafından kaydedilir ve imza sırrı sizin için doldurulur.

Herkese açık site: Yoco webhook'ları mağazanıza gönderir, bu yüzden internetten erişilebilir olmalıdır. Webhook URL'si yönlendirme olmadan bir POST isteğini kabul etmelidir.

VibeFox lisans anahtarı: vibefox.net'ten 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 ya da daha sonra modül listesinde VibeFox Yoco Pay Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. Test gizli anahtarını (sk_test_...) ve hazır olduğunuzda canlı gizli anahtarı (sk_live_...) yapıştırın. Save düğmesine tıklayın. Webhook, anahtarı olan her mod için kaydedilir.

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test mode açıkken bir Yoco test kartıyla test ödemesi yapın, ardından gerçek ödemeleri almak için Test mode seçeneğini kapatın.

Kurulumda modül Yoco payment on hold sipariş durumunu oluşturur. PrestaShop, yeni bir ödeme modülünü tüm para birimleri, ülkeler ve müşteri grupları için 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 Yoco Pay 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, mağaza para birimi ZAR değilse (bu durumda Yoco ödeme sayfasında sunulmaz) ve geçerli modun gizli anahtarı yoksa uyarır; örneğin Enter the test secret key to offer Yoco at checkout (test mode). Kaydettiğinizde modül anahtarları ve webhook sırlarını kontrol eder ve webhook'ları kaydeder. Bununla ilgili mesajlar sayfanın üstünde görünür.

Yoco

Enable/Disable: Enable Yoco ö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 de ödeme yöntemi adı olarak saklanır. Varsayılan: Card or Instant EFT (Yoco).

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

API anahtarları

Gizli anahtarları Yoco Business Portal'da Selling Online > Payment Gateway altından kopyalayın. Yoco'nun iki mod için tek bir API'si vardır: ödemenin test mi gerçek mi olduğuna anahtar karar verir. Test modu yalnızca test anahtarını, canlı mod yalnızca canlı anahtarı kullanır.

Test mode: test gizli anahtarını kullanır. Gerçek para çekilmez; Yoco test kartlarıyla ödeme yapın. Varsayılan: açık. Gerçek ödemeleri almak için kapatın. Açıkken müşteriler ödeme yönteminin altında Test mode — use a Yoco test card; no real money is charged. ifadesini görür.

Test secret key: test modunun gizli anahtarı. sk_test_ ile başlar.

Live secret key: canlı modun gizli anahtarı. sk_live_ ile başlar.

Beklenen önekle başlamayan bir anahtar kaydedilmez: sayfa bir hata gösterir, örneğin Yoco: the test secret key must start with sk_test_ — the previous value was kept. Webhook kaydı sırasında Yoco bir anahtarın diğer moda ait olduğunu bildirirse sayfa bunu size söyler.

Kaydedilmiş anahtarlar ve sırlar 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.

Webhook'lar

Yoco, ödemeleri ve iadeleri bu bölümdeki Webhook URL alanında gösterilen adrese onaylar. Dost URL'ler ile şöyle görünür: https://your-shop/module/wcp_yoco_pay/webhook, başında /en/ gibi bir dil kodu olabilir. Webhook'u Yoco portalında oluşturmanız gerekmez. Ayarları kaydettiğinizde modül, gizli anahtarı olan ama webhook sırrı olmayan her mod için URL'yi Yoco'ya kaydeder ve imza sırrını o modun alanına yazar. Bu modun gizli anahtarı veya webhook URL'si değiştiğinde yeniden kaydeder. URL değiştiğinde eski kayıt silinir.

Her mod için (Test ve Live) bu bölüm webhook'un durumunu gösterir:

Modül bu olayları işler (bunlar bu bölümde de listelenir):

Geçerli imzası olmayan webhook'lar reddedilir. Bir olay, ödemenin yapıldığı modun sırrıyla imzalanmış olmalıdır; bu yüzden bir test sırrı asla canlı bir ödemeyi onaylamaz. URL'yi ayarların gösterdiği gibi birebir kopyalayın, çünkü webhook mağazanıza yönlendirme olmadan ulaşmalıdır.

Test webhook secret: webhook kaydedildiğinde otomatik doldurulur. Sırrı (whsec_...) yalnızca webhook URL'sini kendiniz kaydettiyseniz yapıştırın.

Live webhook secret: webhook kaydedildiğinde otomatik doldurulur. Webhook'u yeniden kaydetmek için temizleyin ve kaydedin.

Webhook sırrı whsec_ ile başlayan ve ardından base64 metni gelen bir biçimde olmalıdır. Başka her değer kaydedilmez ve önceki değer korunur.

Clear saved secrets: bir anahtarı veya sırrı işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş alan kayıtlı değeri korur. Bir webhook sırrını temizleyip kaydetmek webhook'u yeniden kaydeder.

Gelişmiş

Debug log: Yoco isteklerini ve webhook'ları modül klasöründeki logs/yoco_p_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar ve uyarılar, örneğin Yoco'ya başarısız istekler ve reddedilen webhook'lar, her zaman kaydedilir. Anahtarlar, webhook sırları ve e-posta adresleri maskelenir. 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: açıkken modülü kaldırmak ayarları, günlüğü ve modülün Yoco'da kaydettiği webhook'ları siler. Sipariş verileri (Yoco checkout ve ödeme kimlikleri, iadeler) ile Yoco payment on hold sipariş durumu her zaman kalır, çünkü iadeler için gereklidir. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Card or Instant EFT (Yoco)) ve onaylar. Modül, sepet tutarı için kuruş cinsinden bir Yoco checkout'u oluşturur ve müşteriyi Yoco ödeme sayfasına gönderir; müşteri orada kartla veya Instant EFT ile öder. Bu noktada henüz bir sipariş yoktur.

Ödemeyi yaptıktan sonra müşteri mağazanıza döner. Sipariş, yalnızca Yoco onayladıktan sonra ödenmiş olarak işaretlenir: modül, müşteri geri döndüğünde ve imzalı webhook geldiğinde Yoco'dan checkout'u ister. Sipariş ardından oluşturulur ve müşteri Your payment with Yoco has been received. mesajıyla standart sipariş onay sayfasını görür. Müşteri döndüğünde Yoco ödemeyi henüz onaylamadıysa, Payment confirmation sayfasında We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. mesajı ve Check again düğmesi gösterilir; webhook geldiği anda siparişi oluşturur.

Müşteri Yoco sayfasında iptal ederse, The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. mesajıyla ödeme sayfasına döner. Ödeme başarısız olursa mesaj The Yoco payment was not successful. Please try again or choose another payment method. olur. Sepet korunur.

Aynı sepet için yeni bir ödeme denemesinden önce modül öncekini Yoco ile kontrol eder. Zaten ödenmişse sipariş yeni bir ödeme sayfası olmadan oluşturulur. Hâlâ açıksa, aynı tutar için ve 30 dakikadan kısa süre önce oluşturulmuşsa, müşteri aynı Yoco sayfasını yeniden alır. Aksi halde yeni bir Yoco checkout'u oluşturulur.

Yoco ödemeyi başlatamazsa, müşteri Yoco could not start the payment. Please try again in a moment or choose another payment method. mesajıyla ödeme sayfasında kalır ve nedeni günlüğe yazılır. R2,00'nin altındaki bir sipariş Yoco requires an order total of at least R2.00. mesajını alır.

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

Ödemeler Yoco sayfasında hemen tahsil edilir. Modülde kayıtlı kart, abonelik veya yinelenen ödeme yoktur; sitede kart formu ve ayrı yetkilendirme ile tahsilat yoktur ve ZAR dışındaki para birimlerinde çalışmaz.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri Yoco'ya yönlendirildi ve ödeme yapmadı, Yoco sayfasında iptal etti veya Yoco henüz ödemeyi onaylamadı. Yalnızca sepet vardır.

Payment accepted: ödeme onaylandı. Ödeme, Yoco ödeme kimliği işlem kimliği olarak kaydedilir; bir not tutarı, Yoco ödeme ve checkout kimliklerini, modu ve ödemenin nasıl onaylandığını gösterir (müşterinin dönüşü, webhook veya yeni bir ödeme denemesinden önceki kontrol).

Yoco payment on hold: Yoco, sepet toplamından farklı bir tutar veya para birimi bildirdi; örneğin ödeme başladıktan sonra sepet başka bir sekmede değiştirildiği için. Ödeme kaydedilmez, not nedenini açıklar ve müşteri We received your payment and are reviewing it. We will contact you if anything else is needed. mesajını görür. Göndermeden önce ödemeyi kontrol edin. Müşteri başka bir denemeyle doğru tutarı öderse sipariş Payment accepted durumuna geçer.

Cancelled or Refunded: böyle bir siparişe gelen ödeme siparişi değiştirmez. Bir not, ödemeyi Yoco portalında iade etmenizi veya siparişi elle geri yüklemenizi ister. Müşteri Your payment was received after the order had been cancelled. Please contact us — do not pay again. mesajını görür.

Zaten ödenmiş bir siparişe ikinci bir ödeme gelirse sipariş değişmez. Bir not, bunu Yoco portalında iade etmenizi ister.

Yoco ödeme bloğu

Sipariş sayfasında Yoco payment bloğu bulunur; bu blokta Yoco ödeme ve checkout kimlikleri, durum, ödenen ve iade edilen tutar, test ödemeleri için Test mode rozeti, iade geçmişi, sepetin ödeme denemeleri (birden fazlaysa) ve siparişin Yoco notes bölümü yer alır.

İadeler

Yoco payment bölümünde tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Yoco düğmesine tıklayın. Refund this amount through Yoco? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine ihtiyacınız vardır. İadeler Yoco'nun tahsil ettiği tutar üzerinden yapılır; bu yüzden siparişin sonradan düzenlenmiş olsa bile müşterinin gerçekte ödediğinden fazlasını iade edemezsiniz. İade, ödemenin yapıldığı modda (test veya canlı) gönderilir; bu yüzden o modun gizli anahtarı ayarlı olmalıdır. Yanıt kaybolduktan sonra tekrarlanan bir iade iki kez ödenmez.

Başarılı bir iade, Yoco iade kimliğiyle birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna alır; kısmi iade durumu değiştirmez. Yoco iadeyi reddederse blok nedeniyle birlikte Yoco refused the refund: mesajını gösterir ve iade kaydedilmez. Yoco iadeyi beklemede olarak bildirirse blok bunun hâlâ beklemede olduğunu belirtir. Tekrarlamayın: Yoco onayladığında webhook ile kaydedilecektir. İadeler, Yoco checkout ile ödenmiş siparişler için kullanılabilir. Yoco payment on hold durumundaki bir siparişin iade edilecek ödenmiş bir checkout'u yoktur; Yoco portalında iade edin.

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

Yoco portalında yapılan iadeler refund.succeeded webhook'u ile gelir ve iade geçmişine ve notlara kaydedilir. Ödenen tutara ulaştıklarında sipariş Refunded olarak ayarlanır. İade edilebilir kalan tutardan büyük bir iade kaydedilmez ve bir not siparişi kontrol etmenizi ister. Başarısız bir iade, paranın müşteriye geri verilmediğini belirten bir not ekler.

Lisans anahtarı

Modül, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox Yoco Pay Gateway, Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu 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-yoco 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 bir tarihle birlikte License expired on. Mağaza adresi değiştikten sonra ya da 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 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ızdan serbest bırakın.

Etkin bir anahtar olmadan Yoco ö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 sayfasında Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler onaylanmaya devam eder ve iadeler çalışı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 günde bir kez, ardından haftada bir kez. Cron job gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman kaldırır.

Sorun giderme

Yoco ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve geçerli modun gizli anahtarı olduğunu kontrol edin: test modunda Test secret key, canlı modda Live secret key. Sepet para birimi ZAR olmalı ve sipariş toplamı en az R2,00 olmalıdır. Anahtar eksikse veya mağaza para birimi ZAR değilse ayarlar sayfası bir uyarı gösterir. Payment > Preferences bölümünde modülün ZAR, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin.

Ödeme geçti ama sipariş oluşturulmadı: webhook çalışmıyor. Ayarların Webhooks bölümünü açın ve kullandığınız modun durumunu kontrol edin. Kayıtlı değilse veya başka bir URL için kayıtlıysa ayarları kaydedin. Kayıt başarısız olursa sayfa nedenini gösterir. Sırrı kendiniz girdiyseniz, bu URL'nin ve modun webhook'una ait olduğunu kontrol edin. Sipariş ayrıca müşteri ödemeden sonra mağazaya döndüğünde ve müşteri tekrar ödemeyi denediğinde de oluşturulur.

Webhook kaydedilemedi: müşteriler mağazaya döndüğünde ödemeler yine onaylanır. Mesajda gösterilen nedeni giderin, örneğin mağazanın HTTPS üzerinden internetten erişilebilir olması gerekir, ve yeniden kaydedin. URL'yi kendiniz de kaydedebilir ve imza sırrını yapıştırabilirsiniz.

Webhook'lar reddediliyor: reddedilen webhook'lar günlüğe yazılır. webhook secret not configured hiçbir webhook sırrının ayarlanmadığı anlamına gelir. invalid signature sırrın başka bir kayda veya moda ait olduğu anlamına gelir. timestamp outside the tolerance sunucu saatinin yanlış olduğu anlamına gelir: imzalar sunucu zamanından 5 dakika içinde kabul edilir. checkout not completed yet — retry ve could not confirm the checkout with Yoco — retry geçicidir; Yoco webhook'u yeniden gönderir.

Webhook URL'si tarayıcıda yalnızca POST gösteriyor: bu normaldir. URL yalnızca Yoco'dan gelen istekleri kabul eder.

Kaydetmede «The secret key must start with sk_test_ / sk_live_» hatası: bir anahtar yanlış alana yapıştırılmış. Test anahtarı sk_test_, canlı anahtar sk_live_ ile başlar. Önceki değer korundu.

Müşteri Yoco'yu seçerken hata görüyor: modül sayfasındaki Log alanına bakın. Yoco is not available at the moment. Please choose another payment method. mesajı, geçerli modun gizli anahtarı olmadığı anlamına gelir.

Müşteriye bir ödemenin incelenmesi gerektiği bildiriliyor: bir deneme farklı bir tutarla veya sipariş iptal edildikten sonra ödenmiş. Yoco payment bloğundaki notları okuyun ve siparişi tamamlayın ya da ödemeyi Yoco portalında iade edin.

İade, mod ile ilgili bir mesajla başarısız oluyor: ödeme test veya canlı modda yapıldı ve o modun gizli anahtarı ayarlı değil. Anahtarı girin ve yeniden deneyin.

İade, No answer from Yoco mesajıyla başarısız oluyor: PrestaShop'ta hiçbir şey kaydedilmedi. Yoco iadeyi işlediyse aynı iadeyi tekrarlayın: iki kez iade edilmez.

Geliştiriciler: actionYocoPCheckoutPayload kancası, başka bir modülün Yoco checkout'unu oluşturan isteği değiştirmesine izin verir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Yoco Pay 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 açıksa ayarlar, günlük ve modülün Yoco'da kaydettiği webhook'lar silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Yoco checkout'ları ve iadeleri ile Yoco 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ı ve işlem kimliklerini korur.

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