VibeFox Cashfree for WooCommerce — Yardım

Gereksinimler

WordPress: 5.8 veya üzeri.

WooCommerce: 6.0 veya üzeri, kurulu ve etkin olmalı. WooCommerce olmadan eklenti etkinleştirilmez.

PHP: 8.0 veya üzeri.

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

Cashfree hesabı: Cashfree hesabınızın App ID ve Secret Key bilgilerine ihtiyacınız var; test (sandbox) ve canlı ortam için ayrı ayrı. Ayrıca Cashfree Merchant Dashboard'da bir webhook gerekir (bkz. Yapılandırma). Secret Key webhook'ları doğrulamak için de kullanılır; bu nedenle ayrı bir webhook gizli anahtarı yoktur. Sipariş 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. WordPress'te Plugins > Add New > Upload Plugin yolunu izleyin, eklenti ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_cashfree_payment klasörünü FTP ile /wp-content/plugins/ dizinine de yükleyebilirsiniz.

2. Activate düğmesine tıklayın.

3. Ayarları açın: WooCommerce > Settings > Payments > Cashfree Payments > Manage yolunu izleyin veya Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

4. Sayfanın üstündeki lisans bölümüne VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın.

5. 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 ve bir ödeme deneyin.

6. Hazır olduğunuzda canlı App ID ve Secret Key bilgilerini girin ve Sandbox Mode seçeneğinin işaretini kaldırın.

Yapılandırma

Tüm ayarlar tek bir sayfada: WooCommerce > Settings > Payments > Cashfree Payments. Ödeme yöntemi etkinken, seçili modun API anahtarları eksikse sayfa uyarır (bu durumda ödeme yöntemi ödeme sayfasında gizlenir). Test modu açıkken Sandbox mode is on: customers see a test checkout and no real money is charged. ifadesini gösterir. Ağ geçidi etkinken seçili modun anahtarları olmadan kaydederseniz, bunlar girilene kadar ödeme yönteminin ödeme sayfasında gizli kalacağını belirten bir hata mesajı görünür.

Genel

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

Title: müşterilerin ödeme sayfasında gördüğü ödeme yöntemi adı. Varsayılan: Cashfree Payments.

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

Mod ve API anahtarları

App ID ve Secret Key bilgilerinizi Cashfree Merchant Dashboard'da Developers > API Keys altında alın. Test ve canlı ortam anahtarları farklıdır; her birini kendi bölümüne girin.

Sandbox Mode: Enable Sandbox (test) mode test için Cashfree test ortamını kullanır. Gerçek para tahsil edilmez ve ödeme sayfasında SANDBOX MODE - no real payments will be processed. ifadesi gösterilir. Varsayılan: açık. Canlı ödemeler için işaretini kaldırın.

Test kimlik bilgileri

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.

Canlı kimlik bilgileri

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

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

Siparişler, oluşturuldukları ortamı korur. Webhook'ları bu ortamın anahtarlarıyla doğrulanır ve iadeleri bu ortamın anahtarlarıyla gönderilir; bu nedenle canlıya geçtikten sonra test siparişleri kapanana kadar test 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ümde gösterilen URL'yi Payment ve Refund olaylarıyla birlikte ekleyin. Adres şuna benzer: https://your-site/wc-api/cashfree_p/?action=webhook. HTTPS kullanan bir sitede eklenti bu URL'yi her sipariş ile birlikte Cashfree'ye ayrıca iletir. Siteniz HTTPS kullanmıyorsa bu bölümde bir uyarı gösterilir.

Eklenti şu olayları işler:

Cashfree her webhook'u Secret Key'iniz ile imzalar. Geçerli imzası olmayan webhook'lar reddedilir. Bu mağazanın oluşturmadığı siparişlere 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 ödemeden sonra mağazaya döndüğünde onaylanır. Müşteri ödemeden sonra tarayıcıyı kapatırsa siparişi yalnızca webhook onaylayabilir.

Gelişmiş

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

Order ID prefix: Cashfree sipariş kimlikleri, önek + WooCommerce sipariş kimliği olarak oluşturulur; tekrarlanan bir denemeye sonunda bir numara eklenir. Bu sitenin otomatik önekini kullanmak için boş bırakın; bu önek alan açıklamasında gösterilir. Aynı Cashfree hesabına bağlı her mağaza için farklı bir önek kullanın. Yalnızca harfler, rakamlar, "_" ve "-" kullanılabilir, en fazla 20 karakter. Diğer karakterler kaydederken bir mesajla birlikte silinir.

Debug log: Log Cashfree API events for debugging. Hatalar her zaman kaydedilir. Açıkken API çağrıları ve webhook'lar da WooCommerce > Status > Logs bölümüne, kaynak wcp_cashfree_payment olarak yazılır. Anahtarlar ve müşteri verileri hiçbir zaman günlüğe yazılmaz. Varsayılan: kapalı.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Açıkken eklentiyi silmek Cashfree ayarlarını, eklenti günlüklerini ve siparişlerde saklanan Cashfree referanslarını kaldırır. Siparişlerin kendisi korunur. Varsayılan: kapalı.

Ödeme süreci

Müşteri ödeme yöntemini seçer (varsayılan olarak Cashfree Payments) ve siparişi verir. Eklenti, sipariş toplamı için sipariş para biriminde bir Cashfree siparişi oluşturur ve Pay for order sayfasını açar; bu sayfa Redirecting to Cashfree for payment... mesajını gösterir ve 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 öder; örneğin kart, UPI, internet bankacılığı veya cüzdan.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Cashfree onayladıktan sonra ödenmiş olarak işaretlenir: imzalı webhook ile ya da müşteri geri döndüğünde Cashfree'ye sunucudan yapılan bir istekle. Banka ödemeyi henüz onaylamadıysa, sipariş alındı 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ı gösterir.

Ödeme başarısız olur veya müşteri ödemeden Cashfree sayfasından ayrılırsa, müşteri The Cashfree payment was not completed. Please try again or choose another payment method. mesajıyla Pay for order sayfasına döner. Müşteri tekrar denediğinde açık bir Cashfree ödemesi yeniden kullanılır. Sipariş toplamı değiştiyse veya oturumun sona ermek üzere olması durumunda eski Cashfree siparişi kapatılır ve yenisi oluşturulur; böylece sipariş iki kez ödenemez. Sipariş Cashfree'de zaten ödenmiş ama kaydedilmemişse, bir sonraki deneme yeniden tahsilat yapmak yerine ödemeyi kaydeder.

Cashfree ödemeyi başlatamazsa müşteri 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 altındaki bir sipariş toplamı (para biriminin 1 birimi; BHD, JOD, KWD ve OMR için 0,01, TND için 0,1) Cashfree ile ödenemez.

Ödeme yöntemi klasik ödeme sayfasında, Ödeme bloğunda ve Pay for order sayfasında çalışır. WooCommerce High-Performance Order Storage (HPOS) ile uyumludur. Müşteriye gösterilen metinler Hintçeye çevrilmiştir.

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

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri Cashfree'ye yönlendirildi ve henüz ödeme yapmadı ya da ödeme bankada hâlâ beklemede. Müşteri bekleyen bir ödemeyle döndüğünde, eklentinin Cashfree webhook'unu beklediğini belirten bir not eklenir.

Processing: ödeme onaylandı (yalnızca sanal ve indirilebilir ürünlerden oluşan siparişler, WooCommerce varsayılanı olarak Completed olur). Sipariş notunda Cashfree işlem kimliği ve ödeme yöntemi grubu gösterilir. Siparişin işlem kimliği Cashfree ödeme kimliğidir. Sipariş iptal edildikten sonra gelen bir ödeme yine de kaydedilir, çünkü para alınmıştır.

On hold: Cashfree, sipariş toplamından farklı bir ödenen tutar veya para birimi bildirdi. Sipariş notunda beklenen ve alınan tutar ile işlem kimliği gösterilir. Ödemeyi Cashfree panelinde kontrol edin, ardından siparişi manuel olarak tamamlayın veya ödemeyi iade edin.

Failed: ödeme başarısız oldu veya Cashfree'de iptal edildi. Not, Cashfree durumunu ve nedenini gösterir. Her başarısız deneme bir not ekler.

Ödenmiş bir sipariş, daha sonraki bir webhook veya dönüşle asla geri alınmaz.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Cashfree Payments düğmesine tıklayın (düğme, ödeme yönteminin başlığını gösterir). Tam ve kısmi iadeler desteklenir. İade, ödenmiş Cashfree siparişine ve ödendiği ortama (test veya canlı) gönderilir; bu nedenle o ortamın anahtarları ayarlanmış olmalıdır. Cashfree iadeyi kabul etmezse ya da iptal edildi veya reddedildi olarak bildirirse, WooCommerce hatayı gösterir ve hiçbir iade kaydedilmez. Başlatılan bir iade, iade kimliği, tutarı ve durumu ile sipariş notlarına eklenir. Nihai durum, iade webhook'u ile başka bir sipariş notu olarak gelir.

İade durumu webhook'ları yalnızca not olarak eklenir; otomatik olarak WooCommerce iadesi olarak kaydedilmezler.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bölümü, WooCommerce > Settings > Payments > Cashfree Payments sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bölüm durumu gösterir; örneğin lisansın hangi tarihe kadar etkin olduğunu ve alan adınızı. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu siteden kaldırmak için Remove key kullanın. Manage licenses and domains in your account bağlantısı vibefox.net hesabınızı açar.

Bir anahtar bir alan adında çalışır. Anahtarı bir siteden kaldırmak alan adı hakkını serbest bırakmaz. Bu hakkı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar yoksa Cashfree ödeme sayfasında müşterilere gösterilmez. Ödeme yine de başlatılırsa müşteri This payment method is not available. Please choose another one. mesajını görür. Oturum açmış mağaza yöneticileri ödeme yöntemini yine görür; yöntem (unlicensed — visible to admins only) etiketiyle işaretlenir. Böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Plugins sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Lisans süresi dolduğunda eklenti çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum arka planda otomatik olarak yeniden kontrol edilir.

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: test modunda Sandbox App ID ve Sandbox Secret Key, canlı modda App ID ve Secret Key. Sipariş toplamı Cashfree minimumunun altındaysa da ödeme yöntemi gizlenir. Ayarlar sayfası anahtarlar eksik olduğunda uyarı gösterir.

Ödeme yapıldı, ancak sipariş hâlâ Pending payment durumunda: webhook çalışmıyor. Sitenizin HTTPS kullandığını, Developers > Webhooks altındaki URL'nin ayarlarda gösterilenle tam olarak aynı olduğunu ve Payment olaylarının seçili olduğunu kontrol edin. Ayarlardaki Secret Key'in siparişin ödendiği ortama ait olduğunu kontrol edin. Sipariş ayrıca müşteri ödemeden sonra mağazaya döndüğünde ve bir sonraki ödeme denemesinde de onaylanır.

Webhook şu yanıtı veriyor: Missing signature veya Invalid signature: çağrı geçerli bir Cashfree imzası taşımadı ya da ayarlardaki Secret Key, siparişin oluşturulduğu ortamla eşleşmiyor. Cashfree webhook'u yeniden dener.

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

Webhook şu yanıtı veriyor: Busy, retry later: sipariş aynı anda başka bir istek tarafından işleniyordu. Cashfree webhook'u yeniden dener.

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

Müşteri şunu görüyor: We could not start the Cashfree payment: Debug log seçeneğini açın ve WooCommerce > Status > Logs bölümünde, kaynak wcp_cashfree_payment kayıtlarına bakın. Tipik nedenler, seçili mod için yanlış anahtarlar veya Cashfree hesabınızda etkinleştirilmemiş bir para birimidir.

Müşteri şunu görüyor: The minimum amount for a Cashfree payment is …: sipariş toplamı, para birimi için Cashfree minimumunun altındadır.

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

Sipariş ödemeden sonra On hold durumunda: sipariş notunu okuyun. Ödenen tutar veya para birimi siparişten farklıydı. Siparişi tamamlayın veya ödemeyi iade edin.

Refund fails with a message about sandbox or live mode: sipariş o ortamda ödendi ve o ortamın API anahtarları ayarlı değil. Anahtarları girin ve yeniden deneyin.

Lisans bölümü bir hata gösteriyor: bölümdeki mesajı izleyin. Örneğin anahtar başka bir alan adında zaten kullanılıyorsa, vibefox.net hesabınızda bir alan adı hakkını serbest bırakın ve Check now düğmesine tıklayın. Site adresi değiştiyse, anahtarı yeni alan adı için etkinleştirmek üzere Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamıyorsa eklenti son bilinen durumla çalışmaya devam eder.

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Tamamen kaldırmak için Plugins sayfasında devre dışı bırakıp silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ağ geçidi ayarları, siparişlerde saklanan Cashfree verileri ve günlükler yalnızca Delete Data on Uninstall açıksa kaldırılır. Aksi halde yeniden kurulum için saklanır. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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