VibeFox Culqi for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 - 9.x.

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

Mağaza para birimi: Peru Solu (PEN) veya ABD Doları (USD). Culqi başka para birimlerini kabul etmez ve ödeme yöntemi yalnızca PEN veya USD sepetler için gösterilir.

Culqi hesabı: Culqi hesabınızın genel anahtarına ve gizli anahtarına ihtiyacınız vardır. Entegrasyon (test) anahtarları integ-panel.culqi.com adresinden, üretim (canlı) anahtarları mipanel.culqi.com adresinden, CulqiPanel > Desarrollo > API Keys bölümünden alınır. Genel anahtar, tarayıcıdaki Culqi penceresi tarafından kullanılır. Gizli anahtar yalnızca sunucunuzda kullanılır ve hiçbir zaman tarayıcıya gönderilmez. Webhook gerekmez.

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

Kurulum

1. Yönetim panelinde (back office) 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 veya daha sonra modül listesinde VibeFox Culqi Payment öğesini 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ı yapıştırın ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

4. Entegrasyon anahtarlarını ve gerçek ödemeler için üretim anahtarlarını yapıştırın (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test yaparken Test Mode seçeneğini açık tutun, gerçek ödemeleri kabul etmek için kapatın.

6. PEN veya USD'nin mağazanızın etkin para birimi olduğundan emin olun.

Kurulum sırasında modül Culqi payment on hold sipariş durumunu oluşturur. PrestaShop, yeni ödeme modülünü tüm para birimleri, ülkeler ve müşteri grupları için sunar. Bunları Payment > Preferences bölümünden sınırlandırabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Culqi Payment > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Test modu açıkken alanların üstünde sayfa Test mode is active: the integration keys are used and no real money is charged. ibaresini gösterir. Ağ geçidi etkin olduğu halde geçerli modun anahtarları eksikse ve hiçbir mağaza para birimi Culqi tarafından desteklenmiyorsa sayfa uyarır. Her iki durumda da ödeme yöntemi ödeme adımında gizlenir. Varsayılan para biriminiz PEN veya USD değilse sayfa, Culqi'nin yalnızca desteklenen para birimlerindeki sepetler için sunulduğunu belirtir.

Culqi

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

Title: müşterinin ödeme adımında gördüğü ödeme yöntemi adı. Siparişte de ödeme yöntemi adı olarak saklanır. Varsayılan: Credit/Debit Card or Yape (Culqi). Zorunlu.

Description: ödeme adımında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely with your credit/debit card or Yape via Culqi.

API anahtarları

Anahtarları CulqiPanel > Desarrollo > API Keys bölümünden kopyalayın: entegrasyon (test) anahtarları integ-panel.culqi.com'dan, üretim anahtarları mipanel.culqi.com'dan. Test modu yalnızca test anahtarlarını, canlı mod yalnızca canlı anahtarları kullanır. Her anahtar, ait olduğu alanın önekiyle başlamalıdır. Yanlış önekli bir anahtar kaydedilmez: sayfa bir hata gösterir, örneğin Live Secret Key must start with sk_live_ — the previous value was kept., diğer alanlar ise kaydedilir.

Test Mode: açıkken test anahtarları (pk_test_ / sk_test_) kullanılır ve gerçek para tahsil edilmez. Varsayılan: açık. Gerçek ödemeleri canlı anahtarlarla almak için kapatın. Açıkken müşteriler ödeme yönteminin altında TEST MODE: No real charges will be made. ibaresini görür.

Test Public Key: entegrasyon ortamının genel anahtarı. pk_test_ ile başlar.

Test Secret Key: entegrasyon ortamının gizli anahtarı. sk_test_ ile başlar ve hiçbir zaman tarayıcıyla paylaşılmaz.

Live Public Key: üretim ortamının genel anahtarı. pk_live_ ile başlar.

Live Secret Key: üretim ortamının gizli anahtarı. sk_live_ ile başlar ve hiçbir zaman tarayıcıyla paylaşılmaz.

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

Clear saved secret keys: Test Secret Key veya Live Secret Key kutusunu işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş alan kayıtlı değeri korur.

Ödeme yöntemleri

Kartlar her zaman sunulur. Banka havalesi, acenteler, cüzdanlar ve Cuotéalo, Culqi Orders API gerektirir ve bu modül tarafından sunulmaz.

Yape: Offer Yape in the Culqi popup Culqi penceresinde Yape'i kartların yanında gösterir. Varsayılan: açık.

Gelişmiş

Debug log: API isteklerini ve ödeme adımlarını modül klasöründeki logs/culqi_p_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar, kart reddleri dahil kodlarıyla birlikte her zaman kaydedilir. Anahtarlar, kart bilgileri ve müşteri verileri hiçbir zaman 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: açıkken modül kaldırıldığında ağ geçidi ayarları, modüle ait Culqi tahsilat ve iade kayıtları ile günlük silinir. Sipariş durumu ve siparişlerdeki Culqi verileri (ödemeler, notlar) her zaman korunur. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Credit/Debit Card or Yape (Culqi)) ve siparişi onaylama düğmesine tıklar. Culqi Checkout açılır penceresi aynı sayfada, mağaza adınız, sepet toplamı ve para birimiyle açılır. Müşteri orada kart bilgilerini girer veya Yape ile öder. Culqi komut dosyaları yalnızca ödeme sayfasında yüklenir.

Culqi, ödeme verilerini tek kullanımlık bir jetona dönüştürür ve jeton mağazanıza gönderilir. Sunucunuz, Culqi Charges API ile sepet toplamı için sepet para biriminde, hemen tahsil edilen bir tahsilat oluşturur. Tahsilat, CulqiPanel'de Cart ve sepet numarasıyla, müşterinin e-postasıyla birlikte görünür. Bu noktaya kadar sipariş yoktur. Sipariş, yalnızca Culqi onayladıktan sonra ödenmiş olarak işaretlenir: Culqi başarılı bir tahsilat yanıtı verdiğinde sipariş oluşturulur ve müşteri standart sipariş onay sayfasını görür.

Banka 3-D Secure gerektirirse müşteri Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. ibaresini görür. Kimlik doğrulamadan sonra tahsilat otomatik olarak yeniden gönderilir. Doğrulama tamamlanmazsa müşteri The 3-D Secure verification was not completed. Please try again or use another card. ibaresini görür.

Kart reddedilirse müşteri, Culqi'nin mesajını görür, örneğin Payment failed: ve ardından nedeni, ve başka bir kartla yeniden deneyebilir. Culqi yanıt vermezse müşteri We could not confirm your payment with Culqi. Please check your email or contact us before trying again. ibaresini görür. Müşteri Culqi penceresini kapatırsa hiçbir şey tahsil edilmez, müşteri The payment window was closed before the payment was completed. ibaresini görür ve siparişi yeniden verebilir. Bu durumların hepsinde sepet korunur. Başarısız denemeler, henüz sipariş olmadığı için modül günlüğüne yazılır.

Bir sepet asla iki kez tahsil edilmez. Aynı sepetin ödemesi sürerken müşteri yeniden gönderirse This order is already being paid. Please wait a moment and check your email before trying again. ibaresini görür. Culqi parayı tahsil etmiş ama sipariş oluşturulamamışsa müşteri Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. ibaresini görür. Tahsilat korunur ve bir sonraki deneme, yeni bir tahsilat yapmadan bu tahsilattan sipariş oluşturur.

Modül yalnızca kart ve Yape ile tek seferlik ödemeleri kabul eder ve bunları hemen tahsil eder. PagoEfectivo veya CIP kodları, banka uygulaması, acenteler, cüzdanlar ya da Cuotéalo yoktur; kayıtlı kart, abonelik veya taksit yoktur; Culqi webhook'ları yoktur ve ayrı yetkilendirme ile tahsilat yoktur.

Siparişler ve iadeler

Sipariş durumları

No order yet: kart reddedildi, müşteri Culqi penceresini kapattı veya Culqi yanıt vermedi. Yalnızca sepet mevcuttur. Ayrıntılar modül günlüğündedir.

Payment accepted: tahsilat onaylandı ve sepetle eşleşiyor. Ödeme, Culqi tahsilat kimliği (chr_...) ile işlem kimliği olarak kaydedilir; bir not, modu (test veya canlı) ve 3-D Secure'un kullanılıp kullanılmadığını gösterir.

Culqi payment on hold: Culqi, tutarı veya para birimi sepetle eşleşmeyen bir tahsilat bildirdi ya da yetkilendirilmiş ama tahsil edilmemiş bir ödeme bildirdi. Not bunu açıklar ve tahsilat kimliğini gösterir. Sepet para biriminde tahsil edilmiş bir tahsilat, gerçekte tahsil edilen tutar üzerinden ödeme olarak kaydedilir. Tahsilatı CulqiPanel'de kontrol edin, ardından siparişi işleme alın veya ödemeyi iade edin.

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

Zaten siparişi olan bir sepet için ikinci bir tahsilat gelirse sipariş değiştirilmez. Bir not, tahsilatı CulqiPanel'de kontrol etmenizi ve gerekirse iade etmenizi ister.

Culqi payment bloğu

Sipariş sayfasında tahsilat kimliği, tahsil edilen tutar (kullanıldıysa 3-D Secure ile), test ödemeleri için bir Test rozeti, bekletilen siparişler için bir inceleme ipucu, ödenen ve iade edilen tutarlar ile iade geçmişini gösteren bir Culqi payment bloğu bulunur.

İadeler

Culqi payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Culqi düğmesine tıklayın. Refund this amount through Culqi? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modüllere erişim gerekmez. İadeler, Culqi'nin tahsil ettiği tutarda ve para biriminde yapılır; bu nedenle tutar 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ı) anahtarlarıyla gönderilir; mod sonradan değiştirilmiş olsa bile, o modun gizli anahtarının ayarlanmış olması gerekir. Culqi iadeyi kabul etmezse blok hatayı gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, Culqi iade kimliği, tutar ve nedeninizle birlikte iade geçmişine ve sipariş notlarına eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Culqi üzerinden para geri göndermez. CulqiPanel'de yapılan iadeler PrestaShop'a geri senkronize edilmez. Gerekirse siparişi elle güncelleyin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Culqi Payment lisans bloğu, Modules > Module Manager > VibeFox Culqi Payment > 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ı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu son tarih 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-culqi satırı ile 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. 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 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 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 Culqi, ö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. ibaresini 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 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 yine onaylanır ve iadeler çalışır.

Bir lisans süresi dolduğunda 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 boyunca günde bir kez, ardından haftada bir kez. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

Culqi ödeme adımında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu, geçerli modun her iki anahtarının da ayarlı olduğunu (test modunda Test Public Key ve Test Secret Key, canlı modda Live Public Key ve Live Secret Key) ve sepet para biriminin PEN veya USD olduğunu kontrol edin. Ayarlar sayfası anahtarlar eksik olduğunda 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ı, ancak sipariş oluşturulmadı: modül webhook kullanmaz. Tahsilat yalnızca Culqi'nin sunucunuza verdiği yanıtla onaylanır. Culqi zamanında yanıt vermediyse modül günlüğünde sepet numarasıyla birlikte Culqi did not confirm the charge yazar. Bu cart_id ile tahsilatı CulqiPanel'de bulun. Müşteri siparişin tamamlanamadığı mesajını gördüyse, aynı sepetin bir sonraki ödeme denemesi, yeniden tahsilat yapmadan siparişi oluşturur.

Ödemeden sonra sipariş Culqi payment on hold durumunda: siparişteki notu okuyun. Tahsil edilen tutar veya para birimi sepetten farklıydı ya da ödeme tahsil edilmedi. Tahsilatı CulqiPanel'de kontrol edin (kimliği notta yazar), ardından siparişi işleme alın veya ödemeyi iade edin.

Anahtar kaydedilmiyor: hata, alanın sk_live_ gibi bir önekle başlaması gerektiğini söyler. Her alan yalnızca kendi türündeki ve modundaki anahtarları kabul eder: pk_test_, sk_test_, pk_live_ veya sk_live_.

Müşteri şunu görür: Payment gateway misconfiguration. Please contact the store owner.: geçerli modun anahtarları eksik ya da Culqi gizli anahtarı reddetti. Ayarlardaki anahtarları kontrol edin.

Müşteri şunu görür: Payment token is invalid. Please try again.: Culqi penceresinden gelen jeton başka moda ait; örneğin ödeme sayfası açıkken Test Mode değiştirildikten sonra. Müşteri sayfayı yeniden yüklemeli ve tekrar ödemelidir.

Culqi penceresi açılmıyor: müşteri The Culqi payment window could not be loaded. Please reload the page and try again. ibaresini görür. js.culqi.com ve 3ds.culqi.com komut dosyalarının ödeme sayfanızda engellenmediğini kontrol edin; örneğin bir önbellek veya optimizasyon modülü engelliyor olabilir.

Müşteri şunu görür: Security check failed. Please reload the page and try again.: ödeme sayfası çok uzun süre veya başka bir oturumda açık kaldı. Sayfayı yeniden yüklemek sorunu çözer.

Müşteri şunu görür: This order is already being paid: aynı sepet için başka bir ödeme isteği tam o anda çalışıyordu. Müşteri beklemeli ve tekrar denemeden önce e-postasını kontrol etmelidir.

Bir kart reddedildi ve nedenini öğrenmek istiyorsunuz: modül sayfasındaki Log alanına bakın. Debug log kapalı olsa bile reddler Culqi ret koduyla kaydedilir.

İade, anahtarlarla 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 tekrar deneyin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Culqi 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 ağ geçidi ayarları, modüle ait Culqi tahsilat ve iade kayıtları ile günlük silinir. Bundan önce ödenmiş siparişler artık sipariş sayfasından iade edilemez. Kapalıysa her şey sonraki bir yeniden kurulum için korunur. Culqi payment on hold sipariş durumu her zaman korunur. Mevcut siparişler, ödeme notlarını ve işlem kimliklerini korur.

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