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

Flutterwave hesabı: Flutterwave panelinde Settings, API keys altında yer alan hesabınızın gizli anahtarlarına ihtiyacınız var: test modu için FLWSECK_TEST-… ve canlı mod için FLWSECK-…. Yalnızca gizli anahtarlar kullanılır. Genel anahtarlar ve şifreleme anahtarları gerekli değildir. Ayrıca seçtiğiniz gizli hash ile bir webhook kurarsınız (bkz. Yapılandırma).

Para birimleri: Sepet her zaman sepet para biriminde tahsil edilir. Modül ülke veya para birimlerini kendi başına kısıtlamaz; hesabınız para birimini desteklemiyorsa Flutterwave bir hata gösterir. Para birimlerini, ülkeleri ve müşteri gruplarını Payment > Preferences bölümünde sınırlayabilirsiniz.

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

Kurulum

1. Back office'te 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 Flutterwave Payment modülünü bulup Configure düğmesine tıklayın.

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

4. Gizli anahtarlarınızı girin, Flutterwave panelinde webhook'u kurun ve modüle aynı gizli hash değerini girin (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test modunda bir ödeme deneyin, ardından Live mode seçeneğini açın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Flutterwave payment ve Flutterwave payment on hold. PrestaShop, tüm para birimleri, ülkeler ve müşteri grupları için yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünde sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Flutterwave 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 Live mode: real payments are accepted. veya Test mode: no real money is charged. mesajını gösterir. Geçerli modun gizli anahtarı boşsa, canlı anahtar alanında canlı modda bir test anahtarı (FLWSECK_TEST-…) varsa ya da test anahtarı alanında test modunda bir canlı anahtar (FLWSECK-…) varsa uyarır; bu durumda sorun düzeltilene kadar ödeme yöntemi ödeme adımında gizlenir. Ayrıca hiçbir webhook gizli hash'i ayarlanmamışsa uyarır: bu durumda webhook'lar reddedilir ve ödemeler yalnızca müşteri mağazanıza döndüğünde onaylanır. İlk bölümün başlığı geçerli modu gösterir: TEST veya LIVE.

Flutterwave

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

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

Description: müşterilerin ödeme sırasında ödeme yönteminin altında gördüğü metin. Varsayılan: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API anahtarları

Gizli anahtarları Flutterwave panelinde Settings, API keys altından kopyalayın (bölümde bir bağlantı vardır). Test modu ve canlı mod farklı anahtarlar kullanır.

Live mode: gerçek ödemeleri kabul eder. Test modu için kapatın. Test modu test gizli anahtarını kullanır ve gerçek para tahsil edilmez. Canlı mod canlı gizli anahtarı kullanır. Varsayılan: kapalı (test modu). Test modu açıkken müşteriler ödeme yönteminin altında TEST MODE - no real payments will be processed. mesajını görür.

Test Secret Key: Flutterwave test gizli anahtarınız (FLWSECK_TEST-...).

Live Secret Key: Flutterwave canlı gizli anahtarınız (FLWSECK-...).

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

Webhook

Webhook, müşteri mağazanıza dönmese bile ödemeleri onaylar. Flutterwave panelinde Settings, Webhooks altında, bu bölümdeki Webhook URL alanında gösterilen URL'yi ve seçtiğiniz bir gizli hash'i hem test modu hem de canlı mod için girin. Dostça URL'ler kullanıldığında adres şu biçimde görünür: https://your-shop/module/wcp_flutterwave_payment/webhook; bazen /en/ gibi bir dil kodu da içerebilir. URL'yi ayarların gösterdiği gibi birebir kopyalayın. Modül bu olaya tepki verir:

Diğer olaylar yok sayılır.

Secret Hash: webhook gizli hash'i. Flutterwave panelindeki webhook ayarlarındaki değerle eşleşmelidir. Flutterwave bunu her webhook ile birlikte gönderir ve aynı değer test ve canlı mod için kullanılır. Geçerli bir gizli hash içermeyen webhook'lar reddedilir. Webhook olmadan bir ödeme yalnızca müşteri mağazanıza döndüğünde onaylanır.

Clear saved secrets: Test Secret Key, Live Secret Key veya Secret Hash 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

Payment Options: Flutterwave sayfasında gösterilecek, virgülle ayrılmış ödeme yöntemleri; örneğin card, banktransfer, ussd, mobilemoney. Hesabınızda etkin olan tüm yöntemleri göstermek için boş bırakın. Liste kaydetme sırasında düzenlenir (küçük harf, yinelenen değer yok).

Autocomplete Orders: ödenmiş siparişler Payment accepted yerine Delivered durumunu alır ve tek bir durum değişikliği yapılır. Varsayılan: kapalı.

Gelişmiş

Debug log: hata ayıklama için Flutterwave API olaylarını modül klasöründeki logs/flwv_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar her zaman kaydedilir. Anahtarlar, gizli hash ve müşteri verileri asla kaydedilmez. Varsayılan: kapalı.

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

Delete data on uninstall: modül kaldırıldığında modül ayarlarını ve günlükleri siler. Siparişlerde kaydedilen ödeme verileri her zaman saklanır. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Flutterwave) ve onaylar. Geçerli bir e-posta adresi gereklidir. Modül, sepet toplamı için sepet para biriminde bir Flutterwave ödemesi oluşturur; müşterinin e-posta adresi, fatura adresindeki telefon ve ad, mağazanızın adı ve logosu ile birlikte müşteriyi Flutterwave ödeme sayfasına yönlendirir. Orada müşteri, hesabınızda etkin olan yöntemlerden biriyle (veya Payment Options içinde listelenenlerden biriyle) öder. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, ancak Flutterwave ödemeyi onayladıktan sonra ödenmiş olarak işaretlenir: webhook aracılığıyla ya da müşteri döndüğünde sunucu tarafında yapılan bir kontrolle. Sipariş ardından oluşturulur ve müşteri standart sipariş onay sayfasını görür. Ödeme hâlâ bekliyorsa, örneğin banka havalesi, USSD veya mobil para ödemesi, sipariş Awaiting Flutterwave payment durumunda oluşturulur ve sayfada Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. mesajı gösterilir. Sipariş, örneğin ödenen tutar sepetle eşleşmediği için incelemeye alındıysa sayfa Your payment was received and your order is being reviewed. We will contact you if anything is needed. mesajını gösterir. Bekleyen bir ödeme daha sonra başarısız olur ve müşteri onay sayfasını yeniden açarsa sayfa Your Flutterwave payment was not completed. Please contact us about this order. mesajını gösterir.

Müşteri döndüğünde Flutterwave'e ulaşılamazsa, bir Payment confirmation sayfası Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. mesajını ve Check again ile Back to checkout düğmelerini gösterir. Webhook ulaştığı anda siparişi oluşturur.

Ödeme reddedilirse müşteri ödeme adımına döner ve Your payment was declined. You can try again or choose another payment method. mesajını görür. Müşteri Flutterwave sayfasında iptal ederse mesaj Payment was cancelled. You can try again or choose another payment method. olur. Ödeme tamamlanmadıysa mesaj The payment was not completed. You can try again or choose another payment method. olur. Sepet korunur ve müşteri yeniden ödeme yapabilir. Her denemenin kendi referansı vardır ve daha sonra ödenen eski bir ödeme bağlantısı da kabul edilmeye devam eder.

Flutterwave ödemeyi başlatamazsa müşteri ödeme adımında kısa bir mesajla kalır; örneğin Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. Teknik neden günlüğe yazılır.

Ödeme ile onayı arasında sepet değişirse, örneğin başka bir tarayıcı sekmesinde, tutarlar artık eşleşmez ve sipariş bir notla birlikte Flutterwave 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 yalnızca tek seferlik ödemeleri destekler. Sitenizde gömülü veya modal ödeme, kayıtlı kartlar, abonelikler, bölünmüş ödemeler ya da ödeme planları yoktur. Barındırılan ödeme bağlantıları Flutterwave API'si üzerinden iptal edilemez; bu nedenle bir sepetin eski bağlantısı hâlâ ödenebilir.

Siparişler ve iadeler

Sipariş durumları

Henüz sipariş yok: müşteri Flutterwave'e yönlendirildi ve henüz ödeme yapmadı ya da Flutterwave ödemeyi henüz onaylamadı. Yalnızca sepet mevcut.

Payment accepted veya Delivered: ödeme onaylandı. Delivered, Autocomplete Orders açık olduğunda kullanılır. Ödeme, işlem kimliği olarak Flutterwave referansı (flw_ref) ile kaydedilir ve bir not tutarı, ödeme yöntemini, referansı, işlemi ve modu gösterir.

Awaiting Flutterwave payment: müşteri, ödeme Flutterwave'de hâlâ beklerken döndü. Flutterwave ödemeyi onayladığında sipariş ödenmiş duruma geçer.

Flutterwave payment on hold: doğrulanan tutar veya para birimi sepetle eşleşmedi ya da ödeme, sipariş iptal edildikten sonra geldi. Ödeme, gerçekte ödenen tutarla kaydedilir (Flutterwave'in başka bir para biriminde tahsil ettiği tutarla değil). Not bunu açıklar. Siparişi tamamlayın veya ödemeyi iade edin. İptal edilmiş ya da iade edilmiş bir sipariş, tekrarlanan bir webhook ile asla yeniden açılmaz.

Payment error: Flutterwave, bekleyen bir siparişin son ödeme denemesinin başarısız olduğunu veya iptal edildiğini bildirdi. Not nedeni gösterir.

Canceled: sizin tarafınızdan ayarlanır. Flutterwave daha sonra iptal edilmiş bir sipariş için ödeme bildirirse sipariş Flutterwave payment on hold durumuna geçer (yukarıya bakın).

Refunded: ödeme modül üzerinden tamamen iade edildi.

Zaten ödenmiş bir sipariş için ikinci bir ödeme alınırsa sipariş değişmez. Bir not, mükerrer ödemeyi Flutterwave panelinden iade etmenizi ister.

Flutterwave payment bloğu

Sipariş sayfasında, referans (tx_ref), işlem kimliği ve Flutterwave referansı, mod, durum ve ödeme yöntemi, ödenen ve iade edilen tutar, test ödemeleri için bir Test mode rozeti, iade geçmişi ve siparişin Flutterwave notes bölümünü içeren bir Flutterwave payment bloğu gösterilir.

İadeler

Flutterwave payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Flutterwave düğmesine tıklayın. Refund this amount through Flutterwave? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modül sayfalarına erişim gerekmez. İadeler, Flutterwave'in tahsil ettiği tutar ve para biriminde yapılır; bu nedenle tutar ya da para birimi uyuşmazlığından sonra sipariş toplamına değil, müşterinin gerçekte ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı modun (test veya canlı) gizli anahtarıyla gönderilir; bu nedenle o anahtar ayarlanmış olmalıdır. Flutterwave iadeyi reddederse blok hatayı gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, iade geçmişine ve notlara iade kimliği ve durumuyla (completed veya Flutterwave'in bildirdiği durumla initiated) eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. İadeler, Flutterwave ödemeyi onayladıktan sonra kullanılabilir.

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

Flutterwave panelinde yapılan iadeler PrestaShop'a aktarılmaz. Gerekirse sipariş durumunu elle güncelleyin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Flutterwave Payment lisans bloğu, Modules > Module Manager > VibeFox Flutterwave Payment > 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 hangi tarihe kadar etkin olduğu 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-flutterwave 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 yetkisine sahip çalışanlar değiştirebilir. Bloktaki metinler back office dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini belirtir, ö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 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: 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 Flutterwave, ö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 mağazası back office'te oturum açtığınızı bilmez, bu nedenle ödeme yöntemi sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme adımında test edemezsiniz. Modules > Module Manager içinde 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ın süresi dolduğunda modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Back office'te çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonra haftada bir. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

Flutterwave ödeme adımı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ının dolu olduğunu ve moda uyduğunu kontrol edin: test modunda test anahtarı (FLWSECK_TEST-…), canlı modda canlı anahtar (FLWSECK-…). Aksi durumda ayarlar sayfası bir 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 yapıldı ama sipariş oluşturulmadı: webhook çalışmıyor. Flutterwave panelinde webhook URL'sinin Webhook URL alanında gösterilenle birebir aynı olduğunu, kullandığınız modda (test veya canlı) olduğunu ve gizli hash'inin modüldeki Secret Hash ile aynı olduğunu kontrol edin. Bekleyen banka havaleleri, USSD ve mobil para ödemeleri, Flutterwave onaylayana kadar beklemede kalır. Müşteri ödeme yaptıktan sonra mağazaya döndüğünde de sipariş oluşturulur. Debug log seçeneğini açın ve modül sayfasındaki Log alanına bakın.

Webhook şu yanıtı veriyor: Invalid hash veya Secret hash not configured: Flutterwave panelindeki gizli hash modüldekinden farklı ya da modülde hiç hash ayarlanmamış. Aynı değeri iki yere de girin.

Webhook şu yanıtı veriyor: Verification failed, Busy, retry later veya Order could not be created, retry later: ödemeyi doğrulamak için Flutterwave'e ulaşılamadı, işlem henüz görünür değil, sepet başka bir istek tarafından işleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Flutterwave webhook'u yeniden dener. Günlük nedeni gösterir.

Webhook URL'si tarayıcıda Empty body gösteriyor: bu normaldir. URL yalnızca Flutterwave'den gelen webhook'ları kabul eder.

Müşteri Payment gateway is not properly configured mesajını görüyor: geçerli modun gizli anahtarı eksik ya da diğer moda ait.

Müşteri We could not match this payment to an order mesajını görüyor: dönüş bağlantısı, müşterinin sepetine ait olmayan bir referans taşıyor. Müşteriden tahsilat yapıldıysa ödemeyi Flutterwave panelinde bulun.

Flutterwave kendi sayfasında bir hata gösteriyor veya müşteri Flutterwave could not start the payment mesajını görüyor: Flutterwave hesabınız sepet para birimini ya da seçilen ödeme seçeneklerini desteklemiyor olabilir.

Ödemeden sonra sipariş Flutterwave payment on hold durumunda: Flutterwave payment bloğundaki notları okuyun (bkz. Sipariş durumları), ardından siparişi tamamlayın veya ödemeyi iade edin.

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

İade şu yanıtı veriyor: Another operation on this payment is running: o sırada aynı siparişe ait başka bir iade gönderiliyordu. Bir süre bekleyin, iade geçmişini kontrol edin ve gerekirse yeniden deneyin.

Geliştiriciler için: modülün README dosyası actionWcpFlutterwavePaymentRequest (Flutterwave'e gönderilen veriler) ve actionWcpFlutterwaveCurrencyDecimals (para birimi hassasiyeti) hook'larını listeler.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Flutterwave 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 modül ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Siparişlerdeki Flutterwave ödeme verileri ve iadeler ile Awaiting Flutterwave payment ve Flutterwave payment on hold sipariş durumları her zaman saklanır; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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