VibeFox Cashfree for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x.

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

HTTPS: Cashfree webhook'ları yalnızca https:// adreslerine gönderir. HTTPS olmadan da müşteri mağazaya döndüğünde ödemeler onaylanır, ancak canlıya geçmeden önce HTTPS'yi etkinleştirin.

Cashfree hesabı: Cashfree hesabınızın App ID ve Secret Key bilgilerine ihtiyacınız vardır; test (sandbox) ve canlı ortam için ayrı ayrı, ayrıca Cashfree Merchant Dashboard'da bir webhook (bkz. Yapılandırma). Secret Key webhook'ları doğrulamak için de kullanılır, bu nedenle ayrı bir webhook gizli anahtarı yoktur. Sepet para biriminin Cashfree hesabınızda etkin olması gerekir.

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 sayfasına 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 Cashfree Payments 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. Sandbox App ID ve Sandbox Secret Key bilgilerini girin, Cashfree Merchant Dashboard'a webhook'u ekleyin (bkz. Yapılandırma), Enable/Disable seçeneğini açın, Save düğmesine tıklayın ve bir ödeme deneyin.

5. Hazır olduğunuzda canlı App ID ve Secret Key bilgilerini girin, Sandbox Mode seçeneğini kapatın ve Save düğmesine tıklayın.

Kurulumda modül Cashfree payment on hold sipariş durumunu oluşturur. PrestaShop, yeni bir ödeme modülünü tüm para birimleri, ülkeleri ve müşteri gruplarında sunar. Bunları Payment > Preferences altından sınırlandırabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Cashfree Payments > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme sayfanın tamamını kaydeder. Alanların üstünde sayfa, siparişin yalnızca Cashfree ödemeyi onayladıktan sonra oluşturulduğunu açıklar. Ödeme yöntemi etkinleştirildiğinde, sayfa seçili modun API anahtarları eksikse sizi uyarır (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve sandbox modu açıkken Sandbox mode is on: customers see a test checkout and no real money is charged. ifadesini gösterir. Seçili modun anahtarları olmadan etkin bir ödeme yöntemi kaydederseniz, anahtarlar girilene kadar ödeme sayfasında gizli kalacağını belirten bir uyarı çıkar.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments ödeme yöntemini açar veya kapatır. Varsayılan: off.

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

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

App ID ve Secret Key bilgilerinizi Cashfree Merchant Dashboard'da, Developers > API Keys altında bulun. Test ve canlı anahtarlar farklıdır.

Sandbox Mode: test için Cashfree sandbox ortamını kullanır. Gerçek para tahsil edilmez ve ödeme sayfasında ödeme yönteminin altında SANDBOX MODE - no real payments will be processed. görünür. Varsayılan: on. Gerçek ödemeler için kapatın.

Sandbox App ID: Cashfree test ortamınızın App ID değeri.

Sandbox Secret Key: Cashfree test ortamınızın Secret Key değeri.

App ID: Cashfree canlı ortamınızın App ID değeri.

Secret Key: Cashfree canlı ortamınızın Secret Key değeri.

Kaydedilmiş Secret Key değerleri bir daha asla 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: bir Secret Key'in kutusunu işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödemeler, oluşturuldukları ortamı korur. Webhook'ları doğrulanır, durumları kontrol edilir ve iadeleri o ortamın anahtarlarıyla gönderilir. Bu nedenle, canlıya geçtikten sonra sandbox ödemeleri tamamlanana kadar sandbox anahtarlarını dolu tutun.

Webhook

Webhook, mağazanıza bir ödemenin yapıldığını, başarısız olduğunu veya iade edildiğini bildirir. Cashfree Merchant Dashboard'da Developers > Webhooks bölümüne gidin ve bu bölümdeki Webhook URL alanında gösterilen adresi Payment ve Refund olaylarıyla birlikte ekleyin. Dostça URL'lerle şu şekilde görünür: https://your-shop/module/wcp_cashfree_payment/webhook. Adresi, ayarların gösterdiği gibi birebir kopyalayın. HTTPS kullanan bir mağazada modül, her ödemede bu adresi Cashfree'ye de iletir. Mağazanız HTTPS kullanmıyorsa bu bölümde bir uyarı görünür.

Modül bu olayları işler (bunlar da bu bölümde listelenmiştir):

Cashfree her webhook'u Secret Key'iniz ile imzalar. Geçerli bir imzası olmayan webhook'lar reddedilir. Bir webhook, ödemenin yapıldığı ortamın Secret Key'i ile imzalanmalıdır; bu nedenle sandbox anahtarı hiçbir zaman canlı bir ödemeyi onaylamaz. Bu mağaza tarafından başlatılmamış ödemelere ait imzalı webhook'lar (örneğin aynı Cashfree hesabındaki başka bir mağaza) kabul edilir ve yok sayılır. Webhook olmadan sipariş yalnızca müşteri ödeme yaptıktan sonra mağazaya döndüğünde oluşturulur. Müşteri ödemeden sonra tarayıcıyı kapatırsa, siparişi yalnızca webhook (veya aynı sepet için bir sonraki ödeme denemesi) oluşturabilir.

Advanced

API Version: kullanılacak Cashfree API sürümü.

Order ID prefix: Cashfree sipariş kimlikleri, önek + PrestaShop sepet kimliği olarak oluşturulur; aynı sepet için yeni bir deneme sonunda bir numara alır (örneğin 123-2). Alan açıklamasında gösterilen bu mağazanın otomatik önekini kullanmak için boş bırakın. Aynı Cashfree hesabına bağlı her mağaza için farklı bir önek kullanın. Yalnızca harf, rakam, "_" ve "-" kullanılabilir, en fazla 20 karakter. Diğer karakterler kaydetme sırasında uyarıyla birlikte kaldırılır.

Debug log: hatalar her zaman günlüğe kaydedilir. Açıkken Cashfree API çağrıları ve webhook'lar ayrıca modül klasöründeki logs/cashfree_p_debug.log.php dosyasına yazılır. Dosya web üzerinden açılamaz. Anahtarlar ve müşteri verileri hiçbir zaman günlüğe yazılmaz. Varsayılan: off.

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çıkken modülü kaldırmak Cashfree ayarlarını ve modül günlüğünü siler. Siparişler, bunların Cashfree işlemleri ve iadeleri ile Cashfree payment on hold sipariş durumu her zaman korunur, böylece mevcut siparişler çalışmaya devam eder. Varsayılan: off.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini (varsayılan olarak Cashfree Payments) seçer ve onaylar. Modül, sepet toplamı için sepet para biriminde bir Cashfree siparişi oluşturur ve Redirecting to Cashfree for payment... ifadesini gösteren bir ödeme sayfası açarak Cashfree ödeme sayfasını yükler. Kendiliğinden açılmazsa müşteri Pay Now düğmesine tıklayabilir. Cashfree ödeme sayfasında müşteri, Cashfree hesabınızda etkin olan herhangi bir yöntemle (örneğin kart, UPI, internet bankacılığı veya cüzdan) öder. Müşterinin e-posta adresi ve fatura telefonu Cashfree'ye iletilir. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Cashfree ödemeyi onayladıktan sonra ödenmiş olarak işaretlenir: imzalı webhook ile veya müşteri döndüğünde Cashfree'ye yapılan sunucu tarafı bir istekle. Bu noktada sipariş oluşturulur ve müşteri standart sipariş onay sayfasını görür. Dönüş, başka bir tarayıcıda da çalışır; örneğin müşteri bir UPI uygulamasından geri döndüğünde. Banka ödemeyi henüz onaylamadıysa, Payment confirmation sayfası Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. mesajını ve Check again düğmesini gösterir; webhook, banka ödemeyi onaylar onaylamaz siparişi oluşturur.

Ödeme başarısız olur veya müşteri Cashfree sayfasından ödeme yapmadan ayrılırsa, müşteri ödeme sayfasına döner ve The Cashfree payment was not completed. Please try again or choose another payment method. mesajını görür. Sepet korunur. Müşteri tekrar denediğinde açık bir Cashfree ödemesi yeniden kullanılır. Sepet toplamı değişmişse veya oturum sona ermek üzereyse, eski Cashfree siparişi kapatılır ve yenisi oluşturulur; böylece sepet iki kez ödenemez. Sepet Cashfree'de zaten ödenmiş ama kaydedilmemişse, bir sonraki deneme tekrar tahsilat yapmak yerine siparişi oluşturur.

Cashfree ödemeyi başlatamazsa, müşteri ödeme sayfasında kalır ve We could not start the Cashfree payment. Please try again or choose another payment method. mesajını görür. Teknik neden günlüğe yazılır. Cashfree minimumunun (para biriminin 1 birimi; BHD, JOD, KWD ve OMR için 0,01 ve TND için 0,1) altındaki sepet toplamı Cashfree ile ödenemez ve bu sepet için ödeme yöntemi gösterilmez.

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

Modül yalnızca Cashfree ödeme sayfasında tek seferlik ödemeleri kabul eder. Kayıtlı kart, abonelik veya yinelenen ödeme yoktur; ayrı bir ön provizyon ve tahsilat işlemi yoktur; Cashfree teklif bileşeni, Cashfree üzerinden kapıda ödeme (COD) veya ödeme bağlantıları yoktur ve para birimi dönüşümü yoktur: sepet, sepet para biriminde tahsil edilir.

Siparişler ve iadeler

Order statuses

No order yet: müşteri Cashfree'ye yönlendirildi ve ödeme yapmadı, ödeme başarısız oldu veya ödeme bankada hâlâ beklemede. Yalnızca sepet vardır.

Payment accepted: ödeme onaylandı. Ödeme, Cashfree ödeme kimliği işlem kimliği olarak kaydedilir; bir notta işlem kimliği ve ödeme yöntemi grubu (örneğin upi veya credit_card) gösterilir.

Cashfree payment on hold: Cashfree, sepet toplamından farklı bir ödenen tutar veya para birimi bildirdi (örneğin ödeme başladıktan sonra sepet başka bir sekmede değiştirildi). Notta beklenen ve alınan tutar ile işlem kimliği gösterilir. Ödemeyi Cashfree panelinde kontrol edin, ardından siparişi tamamlayın veya ödemeyi iade edin.

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

Sipariş iptal edildikten sonra gelen bir ödeme yine kaydedilir ve sipariş yeniden ödenmiş olur, çünkü para tahsil edilmiştir. Ödenmiş bir sipariş, sonradan başarısız olan bir ödemeyle asla geri alınmaz.

Cashfree payment block

Sipariş sayfasında işlem kimliği, Cashfree siparişi, ödeme durumu, ödenen ve iade edilen tutar, sandbox ödemeleri için bir Sandbox rozeti, iade geçmişi ve siparişin Cashfree notes bölümünü içeren bir Cashfree payment bloğu gösterilir.

Refunds

Cashfree payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Cashfree düğmesine tıklayın. Refund this amount through Cashfree? 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, Cashfree'nin tahsil ettiği tutar ve para biriminde yapılır; bu nedenle tutar uyuşmazlığından sonra sipariş toplamını değil, müşterinin gerçekte ödediği tutara kadar iade yapabilirsiniz. İade, ödendiği ortamda (sandbox veya canlı) ödenmiş Cashfree siparişine gönderilir; bu nedenle o ortamın anahtarları girilmiş olmalıdır. Cashfree iadeyi kabul etmezse veya iptal edildi ya da reddedildi olarak bildirirse, blokta hata gösterilir ve hiçbir iade kaydedilmez. Başlatılan bir iade, iade kimliği, tutarı ve durumuyla birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir; kısmi iade durumu değiştirmez. İadeler, Cashfree ödemeyi onayladıktan sonra kullanılabilir.

Nihai iade durumu, iade webhook'u ile gelir ve notlara eklenir. Modül kredi notu oluşturmaz. Sipariş sayfasındaki PrestaShop'un standart iade düğmeleri, Cashfree üzerinden para geri göndermez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Cashfree Payments lisans bloğu, Modules > Module Manager > VibeFox Cashfree Payments > 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ı 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-cashfree 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 yetkisi olan çalışanlar değiştirebilir. Bloğun metinleri yönetim paneli dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini açıklar; ö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 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 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, Cashfree ö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. Mağaza ön yüzü, 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, ama ödeme sayfası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 yine onaylanır ve iadeler çalışmaya devam eder.

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

Cashfree ö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 anahtarlarının bulunduğunu kontrol edin: sandbox modunda Sandbox App ID ve Sandbox Secret Key, canlı modda App ID ve Secret Key. Anahtarlar eksikse ayarlar sayfası bir uyarı gösterir. Sepet toplamı Cashfree minimumunun altındaysa da ödeme yöntemi gizlenir. 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. Mağazanızın HTTPS kullandığını, Developers > Webhooks altındaki adresin Webhook URL alanında gösterilenle birebir aynı olduğunu ve Payment olaylarının seçili olduğunu kontrol edin. Ayarlardaki Secret Key'in ödemenin yapıldığı ortama ait olduğunu doğrulayın. Cashfree paneli, her webhook için mağazanızın yanıtını gösterir. Sipariş, müşteri ödemeden sonra mağazaya döndüğünde ve aynı sepet için bir sonraki ödeme denemesinde de oluşturulur.

Webhook, Missing signature veya Invalid signature yanıtı veriyor: çağrı geçerli bir Cashfree imzası taşımıyordu veya ayarlardaki Secret Key, ödemenin yapıldığı ortamla eşleşmiyor. Sandbox ve canlı anahtarların karıştırılmadığını kontrol edin.

Webhook, Ignored yanıtı veriyor: webhook doğru imzalanmış, ancak bu mağaza tarafından başlatılmamış bir ödemeye ait; örneğin aynı Cashfree hesabındaki başka bir mağaza. Her mağazaya kendi Order ID prefix değerini verin.

Webhook, Busy, retry later yanıtı veriyor: sipariş aynı anda başka bir istek tarafından oluşturuluyordu veya sipariş oluşturulamadı (örneğin modül devre dışı). Cashfree webhook'u yeniden dener. Nedeni görmek için Debug log seçeneğini açın.

Müşteri The Cashfree payment page could not be loaded mesajını görüyor: Cashfree betiği tarayıcıda yüklenemedi, örneğin bir engelleyici nedeniyle. Müşteri Pay Now veya Choose another payment method düğmesine yeniden tıklayabilir.

Müşteri We could not start the Cashfree payment mesajını görüyor: modül sayfasındaki Log alanına bakın. Tipik nedenler, seçili mod için yanlış anahtarlar veya Cashfree hesabınızda etkinleştirilmemiş bir para birimidir.

Müşteri We could not verify the payment mesajını görüyor: dönüş bağlantısı sepetle eşleşmedi. Para tahsil edildiyse webhook yine siparişi oluşturur. Müşteri yeniden ödeme yapmadan önce ödemeyi Cashfree panelinde kontrol edin.

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

İade, sandbox veya canlı mod ile ilgili bir mesajla başarısız oluyor: ödeme o ortamda yapılmıştır ve o ortamın API anahtarları girilmemiştir. Anahtarları girin ve yeniden deneyin.

Kaldırma

Modules > Module Manager sayfasına gidin, VibeFox Cashfree Payments 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 Cashfree ayarları ve günlük silinir. Kapalıysa, daha sonra yeniden kurmak için tüm ayarlar saklanır. Cashfree işlemleri ve iadeleri ile Cashfree 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.

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