VibeFox Razorpay for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

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

Razorpay hesabı: test modu için Razorpay hesabınızın Key ID ve Key Secret bilgilerine, canlı mod için ise hesabınız etkinleştirildikten sonra bu bilgilere ihtiyacınız var. Seçtiğiniz bir secret ile webhook oluşturmanız kesinlikle önerilir (bkz. Yapılandırma). INR dışındaki para birimlerinde yapılan ödemeler için Razorpay hesabınızda International Payments etkinleştirilmelidir.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar 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 ya da daha sonra modül listesinde VibeFox Razorpay Payment modülünü 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 Key ID ve Test Key Secret bilgilerinizi girin, Razorpay Dashboard'da webhook'u ayarlayın ve secret'ını girin (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test mode açıkken bir test ödemesi yapın. Hazır olduğunuzda Live anahtarlarını girin ve Test mode seçeneğini kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Razorpay payment authorized ve Razorpay 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ünden sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Razorpay Payment > 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 uyarılar gösterir: geçerli modun anahtarları eksiktir (bu durumda Razorpay ödeme sayfasında gösterilmez), test modunda Key ID rzp_test_ ile, canlı modda ise rzp_live_ ile başlamıyordur, test modu açıktır, webhook secret boştur ya da mağazanın varsayılan para birimi INR değildir ve Razorpay hesabınızda International Payments gerektirir. Key ID'lerle birlikte yapıştırılan boşluklar kaydetme sırasında silinir.

Razorpay

Enable/Disable: Enable Razorpay Payment Gateway ö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 kaydedilen ödeme yöntemi adı da budur. Varsayılan: UPI, Cards, NetBanking. Zorunlu: boş bir başlık Enter a title for the payment method. hatasına yol açar.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

API anahtarları

Anahtarlarınızı Razorpay Dashboard'da Account & Settings > API Keys altında alın. Test anahtarları (rzp_test_...) oluşturmak için Dashboard'u Test moduna alın. Canlı anahtarlar (rzp_live_...) hesabınız etkinleştirildikten sonra kullanılabilir.

Test mode: Test modu anahtarlarını kullanır, bu nedenle gerçek para tahsil edilmez. Varsayılan: açık. Gerçek ödemeleri kabul etmek için kapatın. Bir siparişin ödemeleri, tahsilatları ve iadeleri her zaman siparişin ödendiği modun anahtarlarını kullanır; bu nedenle modu daha sonra değiştirmek mevcut siparişleri etkilemez.

Test Key ID: Razorpay Dashboard'da Test modundaki Key ID. rzp_test_ ile başlar.

Test Key Secret: Razorpay Dashboard'da Test modundaki Key Secret.

Live Key ID: Razorpay Dashboard'da Live modundaki Key ID. rzp_live_ ile başlar.

Live Key Secret: Razorpay Dashboard'da Live modundaki Key Secret.

Kaydedilmiş secret'lar 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.

Kayıtlı secret'ları temizle: Test Key Secret, Live Key Secret veya Webhook Secret seçeneğini işaretleyip Save düğmesine tıklayarak kaldırın. Boş bir alan kayıtlı değeri korur.

Ödeme

Payment Action: paranın ne zaman tahsil edileceği. Varsayılan: Authorize & Capture.

Authorize & Capture: müşteri hemen ücretlendirilir. Razorpay yetkilendirilmiş bir ödeme bildirirse modül bunu tahsil eder.

Authorize Only: tutar ayrılır. Sipariş Razorpay payment authorized durumunda oluşturulur ve ödemeyi daha sonra sipariş sayfasındaki Razorpay bloğunda Capture Razorpay payment ile ya da Razorpay Dashboard'da tahsil edersiniz. Zamanında tahsil edilmeyen yetkilendirilmiş ödemeleri Razorpay otomatik olarak iade eder.

Webhook

Webhook, müşteri ödemeden hemen sonra tarayıcıyı kapatsa bile ödemeleri onaylar ve Razorpay Dashboard'da yapılan iadeleri kaydeder. Razorpay Dashboard'da Account & Settings > Webhooks bölümüne gidin; Test modunda bir webhook, Live modunda başka bir webhook ekleyin. Bu bölümdeki Webhook URL alanında gösterilen URL'yi kullanın. Dostça URL'ler açıkken şuna benzer: https://your-shop/module/wcp_razorpay_payment/webhook; başına /en/ gibi bir dil kodu da eklenmiş olabilir. Ayarlarda gösterildiği gibi birebir kopyalayın. Razorpay'de kendi seçtiğiniz bir secret girin ve şu olayları seçin (bu bölümde de listelenmiştir):

payment.authorized: bir ödeme yetkilendirildi.

payment.captured: bir ödeme tahsil edildi; Razorpay Dashboard'da tahsil ettiğinizde de bu olay gerçekleşir.

payment.failed: bir ödeme denemesi başarısız oldu.

order.paid: ödemenin ait olduğu Razorpay siparişi ödendi.

refund.created: bir ödeme iade edildi, örneğin Razorpay Dashboard'da.

Webhook Secret: webhook oluştururken girdiğiniz secret. Modülde test ve canlı webhook için tek bir alan bulunduğundan, her ikisinde de aynı secret'ı kullanın. Geçerli imzası olmayan webhook'lar reddedilir. Webhook olmadan bir ödeme yalnızca müşteri pencereden döndüğünde ya da müşteri aynı sepet için ödemeyi daha sonra yeniden başlattığında onaylanır.

Gelişmiş

Enable Logging: günlük, modül klasöründeki logs/razorpay_p_debug.log.php dosyasına yazılır. Dosya web üzerinden açılamaz. Hatalar ve uyarılar her zaman günlüğe yazılır; bu seçenek hata ayıklama ayrıntılarını ekler. Anahtarlar, imzalar ve müşteri iletişim bilgileri hiçbir zaman günlüğe yazılmaz. Varsayılan: kapalı.

Log: günlüğün boyutunu ve 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ırıldığında modül ayarları ve günlük silinir. Siparişler, Razorpay işlemleri ve iadeleri ile modülün sipariş durumları her zaman korunur. Varsayılan: kapalı.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak UPI, Cards, NetBanking) ve onaylar. Modül, sepet tutarı ve para birimi için bir Razorpay siparişi oluşturur ve mağazanızın Razorpay payment sayfasını açar. Razorpay Checkout açılır penceresi bu sayfada otomatik olarak açılır; müşterinin adı, e-posta adresi ve telefonu önceden doldurulmuştur. Ödeme Razorpay'de Cart olarak ve sepet numarasıyla görünür. Bu aşamada henüz bir PrestaShop siparişi yoktur. Pencere kapatılırsa müşteri onu yeniden açmak için Pay Now düğmesine ya da ödeme sayfasına dönmek için Choose another payment method düğmesine tıklayabilir. Sepet korunur. Test modunda sayfa Razorpay Test mode: no real money will be charged. ifadesini gösterir.

Başarılı bir ödemeden sonra müşteri Please wait while we process your payment... mesajını görür. Modül Razorpay imzasını kontrol eder, ödemeyi Razorpay API'sinden alır ve tutarı ile para birimini sepetle karşılaştırır. Sipariş yalnızca Razorpay onayladıktan sonra ödenmiş olarak işaretlenir. Ardından sipariş oluşturulur ve müşteri standart sipariş onay sayfasını görür. İmza geçerli olduğu halde ödeme o anda alınamazsa sipariş Razorpay payment on hold durumunda oluşturulur ve webhook bunu daha sonra onaylar.

Müşteri aynı sepet için ödemeyi yeniden başlatırsa, tutar, para birimi ve mod değişmemişse modül mevcut Razorpay siparişini yeniden kullanır. Bu Razorpay siparişi zaten ödenmişse (örneğin müşteri tarayıcıyı kapattığı ve webhook olmadığı için), modül ikinci bir ödeme istemek yerine siparişi bu ödemeden oluşturur. Sepet toplamı değiştiyse yeni bir Razorpay siparişi oluşturulur.

Müşterinin görebileceği mesajlar:

Your session has expired. Please click "Pay Now" to try again.

We could not verify your payment. Mesaj, para çekildiyse Razorpay ödemeyi onayladığında siparişin otomatik olarak güncelleneceğini ekler.

This payment method is not available right now. Please choose another payment method. Anahtarlar eksik ya da hatalı.

Razorpay is temporarily unavailable. Please try again in a few minutes.

Razorpay could not accept this payment: ardından Razorpay'in belirttiği neden gelir.

The order amount is too small to be paid with Razorpay.

Razorpay Checkout could not be loaded. Açılır pencere betiği engellendi; mesaj bağlantıyı kontrol etmeyi, içerik engelleyicileri devre dışı bırakmayı ve sayfayı yeniden yüklemeyi ister.

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

Modül yalnızca tek seferlik ödemeleri destekler. Abonelik ya da tekrarlayan ödeme, kayıtlı kart, Razorpay Magic Checkout, Payment Links veya Route (bölünmüş ödemeler) ve teklif ya da uygunluk widget'ları yoktur.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri ödeme yapmadı ya da Razorpay ödemeyi henüz onaylamadı. Yalnızca sepet vardır. Başarısız bir ödeme denemesi sipariş oluşturmaz; müşteri yeniden ödeyebilir.

Payment accepted: ödeme tahsil edildi ve onaylandı. Ödeme, işlem kimliği olarak Razorpay ödeme kimliğiyle (pay_...) kaydedilir; bir not ödeme kimliğini, tutarı ve onay şeklini (callback, webhook, sync veya admin) gösterir.

Razorpay payment authorized: ödeme yalnızca yetkilendirildi (Authorize Only). Siparişi tamamlamak için tahsil edin.

Razorpay payment on hold: bu durumlarda ayarlanır ve her biri bir notla kaydedilir: ödenen tutar ya da para birimi sepetle eşleşmedi (örneğin ödeme başladıktan sonra sepet değiştirildi), ödeme iptal edilmiş bir sipariş için tahsil edildi ya da ödeme o anda Razorpay API üzerinden doğrulanamadı. Sipariş para birimindeki ödenen tutar siparişe kaydedilir. Siparişi kontrol edin ve işleme alın ya da ödemeyi iade edin.

Cancelled: iptal edilmiş bir sipariş için sonradan gelen ödeme siparişi otomatik olarak yeniden açmaz: yetkilendirilmiş bir ödeme tahsil edilmez ve yalnızca bir not alır, tahsil edilmiş bir ödeme ise siparişi Razorpay payment on hold durumuna alır. Siparişi ödemiş olan ödemenin tekrarlanan bildirimi, siparişi sonradan iptal etmiş olsanız bile hiçbir şeyi değiştirmez.

Refunded: ödeme tamamen iade edildi.

Zaten ödenmiş bir sipariş için ek bir ödeme gelirse sipariş değişmez. Amaçlanmadıysa bir not sizden bunu Razorpay Dashboard'da iade etmenizi ister. Ödenmiş bir sipariş için geç gelen bir payment.failed yalnızca bir not ekler.

Razorpay ödeme bloğu

Sipariş sayfasında Razorpay ödeme kimliği, Razorpay siparişi, ödeme durumu, Paid / refunded (Razorpay'in tahsil ettiği tutar ve iade edilen tutar), test ödemeleri için Test mode rozeti, iade geçmişi ve siparişin Razorpay notes bölümünü içeren bir Razorpay payment bloğu gösterilir. Tahsilat ve iadeler için sipariş düzenleme yetkisi gerekir; modül yapılandırmasına erişim gerekmez.

Tahsilat (Authorize Only)

Siparişi Razorpay payment authorized durumunda açın, Razorpay bloğundaki Capture Razorpay payment düğmesine tıklayın ve onaylayın. Ödeme yetkilendirildiği modda tahsil edilir ve sipariş Payment accepted olur. Razorpay reddederse blok ve notlar nedeniyle birlikte Razorpay capture failed: ifadesini gösterir. Razorpay Dashboard'da yapılan bir tahsilat, webhook aracılığıyla siparişi tamamlar.

İadeler

Razorpay bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isterseniz bir neden yazın ve Refund via Razorpay düğmesine tıklayın. Refund this amount through Razorpay? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. İadeler, Razorpay'in tahsil ettiği tutar ve para biriminde yapılır; bu nedenle tutar uyuşmazlığından sonra sipariş toplamına değil, müşterinin gerçekten ödediği tutara kadar iade yapabilirsiniz. Daha yüksek bir tutar Invalid refund amount: at most ifadesini ve tutarı gösterir. İade, ödemenin yapıldığı modun anahtarlarıyla gönderilir. Razorpay iadeyi kabul etmezse blok Razorpay refund failed: ve nedeni gösterir; hiçbir iade kaydedilmez. Başarılı bir iade, Razorpay 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, ödeme tahsil edildikten sonra kullanılabilir.

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

Razorpay Dashboard'da yapılan iadeler webhook ile gelir ve iade geçmişine ile notlara bir kez kaydedilir. Sipariş tamamen iade edildiğinde durumu Refunded olur. Farklı bir para biriminde ya da iade edilebilir tutardan büyük yapılan bir Dashboard iadesi otomatik kaydedilmez; bir not sizden bunu elle kaydetmenizi ister.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Razorpay Payment lisans bloğu, Modules > Module Manager > VibeFox Razorpay 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ı maskeli olarak, durumunu (örneğin lisansın hangi tarihe kadar geçerli 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-razorpay 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ün Configure iznine sahip çalışanlar değiştirebilir. Bloktaki metinler 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 bir alan adında çalışır: ana mağazanın alan adında, çok mağazalı kurulumda 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 Razorpay ö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 nedenle ödeme yöntemi sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, 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 yine onaylanır, tahsilat ve iadeler çalışır.

Lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek yenileme gerektirir. Durum, yönetim panelinde çalışırken 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

Razorpay ö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 iki anahtarın da bulunduğunu kontrol edin: Test modunda Test Key ID ve Test Key Secret, Live modunda Live Key ID ve Live Key Secret. Eksik olduklarında 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 alındı ama sipariş oluşturulmadı: webhook çalışmıyor. Razorpay Dashboard'da, kullandığınız modda (Test ya da Live) webhook'un var olduğunu, URL'sinin Webhook URL alanında gösterilenle birebir aynı olduğunu ve beş olayın seçili olduğunu kontrol edin. Webhook Secret değerinin Razorpay'deki secret ile aynı olduğunu doğrulayın. Müşteri pencereden döndüğünde ya da aynı sepet için ödemeyi yeniden başlattığında da sipariş oluşturulur.

Webhook şu yanıtı veriyor: Webhook secret not configured: Webhook Secret boş. Razorpay webhook'unun secret'ını girin. Razorpay olayı daha sonra yeniden gönderecektir.

Webhook şu yanıtı veriyor: Invalid signature veya Missing signature: ayarlardaki secret, Razorpay webhook'unun secret'ından farklı. Test ve Live webhook için iki yere de aynı secret'ı girin.

Webhook şu yanıtı veriyor: Retry later: modül bir tahsilatı Razorpay API ile onaylayamadı, sipariş oluşturulamadı (örneğin modül devre dışı) ya da sepet aynı anda başka bir istek tarafından güncelleniyordu. Razorpay olayı otomatik olarak yeniden gönderecektir. Nedeni Log alanındadır.

Webhook URL'si tarayıcıda Method not allowed gösteriyor: bu normaldir. URL yalnızca Razorpay'den gelen istekleri kabul eder.

Bir sipariş Razorpay payment on hold durumunda: Razorpay bloğundaki notları okuyun. Tutar ya da para birimi sepetle eşleşmedi, ödeme iptal edilmiş bir sipariş için geldi ya da o anda Razorpay API üzerinden doğrulanamadı ve webhook'u bekliyor.

Müşteri ödeme sırasında bir hata görüyor: modül sayfasındaki Log alanına bakın. Hatalar Enable Logging kapalıyken de günlüğe yazılır. Yanlış anahtarlar, ödeme yönteminin o an kullanılamadığı mesajını verir. Razorpay'in diğer nedenleri Razorpay could not accept this payment: ifadesinden sonra gösterilir.

Açılır pencere açılmıyor: Razorpay Checkout betiği bir içerik engelleyici ya da bağlantı nedeniyle engellendi. Müşteri bir mesaj görür ve sayfayı yeniden yükleyebilir.

Tahsilat ya da iade, mod ile ilgili bir mesajla başarısız oluyor: ödeme Test ya da Live modunda yapıldı ve o modun anahtarları tanımlı değil. Anahtarları girin ve yeniden deneyin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Razorpay 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. Razorpay işlemleri ve iadeleri ile Razorpay payment authorized ve Razorpay payment on hold sipariş durumları her zaman korunur; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da tahsil edilebilir ve iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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