VibeFox OpenPay for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

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

HTTPS: kart formu ödeme sayfanızda olduğu için mağazanız HTTPS kullanmalıdır.

OpenPay hesabı: Meksika, Kolombiya veya Peru'dan bir OpenPay hesabı. Merchant ID'sine, özel anahtarına (sk_...) ve genel anahtarına (pk_...) ihtiyacınız vardır. Sandbox ve canlı panelleri farklı Merchant ID'lere ve anahtarlara sahiptir; modül bunları ayrı tutar.

VibeFox lisans anahtarı: vibefox.net'ten satın alınır. Bir anahtar bir alan adında çalışır.

Kart, ödeme sayfanızda girilir ancak tarayıcıda openpay.js tarafından okunur ve jetonlaştırılır. Kart alanlarının adı yoktur ve sunucunuza asla gönderilmez. Kart formu sayfanızda olduğu için PCI DSS kapsamınız SAQ A-EP'dir; acquirer'ınıza (ödeme hizmeti sağlayıcınıza) danışın.

Kurulum

1. Yönetim panelinde Modules > Module Manager yolunu izleyin 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 VibeFox OpenPay Gateway modülünü daha sonra modül listesinde bulup Configure düğmesine tıklayın.

3. Configure sayfasının üstündeki lisans bloğunda bulunan License key alanına VibeFox lisans anahtarınızı yapıştırın ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

4. Account country seçin ve sandbox ile canlı anahtarlarını girin (bkz. Yapılandırma).

5. Önerilir: OpenPay panelinde webhook URL'sini ekleyin (bkz. Yapılandırma).

6. Enable / Disable seçeneğini açın ve Save düğmesine tıklayın. OpenPay sandbox test kartlarıyla bir ödeme deneyin, ardından gerçek ödemeleri kabul etmek için Sandbox mode seçeneğini kapatın.

Kurulum sırasında modül iki sipariş durumu oluşturur: Awaiting OpenPay payment ve OpenPay payment on hold. PrestaShop, mağazanızın para birimleri, ülkeleri 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 OpenPay Gateway > 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; mevcut modun anahtarları eksikse (ödeme yöntemi bu durumda ödeme sayfasında gizlenir), mağazanızın varsayılan para birimi seçilen hesap ülkesi tarafından kabul edilmiyorsa uyarır ve sandbox modu açıkken Sandbox mode is enabled — no real charges are made. mesajını gösterir.

Kaydederken anahtarlar kontrol edilir. Merchant ID yalnızca harf ve rakam içerebilir; özel anahtar sk_ ile, genel anahtar pk_ ile başlamalıdır. Geçersiz bir değer kaydedilmez: önceki değer korunur ve örneğin Sandbox: The private key must start with sk_. gibi bir hata gösterilir. Ödeme yöntemi etkinse ama mevcut modun anahtarları eksikse, ödeme yönteminin ödeme sayfasında gizli kalacağına dair bir mesaj da görürsünüz. Boş bir Title Enter a title for the payment method. mesajıyla reddedilir.

OpenPay

Enable / Disable: Enable OpenPay card payments ö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: Credit or debit card (OpenPay). Zorunlu.

Description: ödeme sayfasında kart formunun üstünde gösterilen metin. Varsayılan: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

OpenPay hesabı

Merchant ID, özel anahtar (sk_) ve genel anahtar (pk_), OpenPay panelinizde Settings (Configuración) altında bulunur. Bölümde Meksika, Kolombiya ve Peru'nun sandbox ve canlı panellerine bağlantılar vardır.

Account country: OpenPay hesabınızın ülkesi. OpenPay API'sini, o ülkenin openpay.js kitaplığını ve kabul edilen para birimlerini belirler. Varsayılan: Mexico.

Sandbox mode: OpenPay sandbox'ını kullanır (test anahtarları, gerçek tahsilat yok) ve hem anahtarları hem API'yi sandbox'a geçirir. Açıkken ödeme sayfasında SANDBOX MODE rozeti gösterilir. Varsayılan: açık. Gerçek ödemeleri almak için kapatın.

Sandbox Merchant ID: sandbox panelindeki Merchant ID, Settings (Configuración), API anahtarları.

Sandbox Private Key: sandbox özel anahtarı. sk_ ile başlar. Yalnızca sunucuda kullanılır; asla paylaşmayın.

Sandbox Public Key: sandbox genel anahtarı. pk_ ile başlar. openpay.js bunu kartı jetonlaştırmak için tarayıcıda kullanır.

Live Merchant ID: canlı paneldeki Merchant ID, Settings (Configuración), API anahtarları.

Live Private Key: canlı özel anahtar (sk_...).

Live Public Key: canlı genel anahtar (pk_...).

Kayıtlı özel anahtarlar bir daha 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 özel anahtarı işaretleyip Save düğmesine tıklayarak kaldırın. Boş alan kayıtlı değeri korur.

Webhook

Webhook zorunlu değildir, ancak önerilir. Müşteri 3D Secure sayfasından dönmediğinde, örneğin tarayıcıyı kapattıktan sonra ödemeleri onaylar. OpenPay panelinde Settings > Webhooks bölümüne gidin ve bu bölümde Webhook URL altında gösterilen URL'yi ekleyin. Dostu URL'lerle şöyle görünür: https://your-shop/module/wcp_openpay_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. Ayarların gösterdiği gibi birebir kopyalayın. Kullandığınız her mod için (sandbox ve canlı) panelde webhook ekleyin.

Webhook eklediğinizde OpenPay bu URL'ye bir doğrulama kodu gönderir. Kod, geldiği tarihle birlikte bu bölümde görünür; böylece webhook'u OpenPay panelinde onaylayabilirsiniz.

Şu olayları seçin (bunlar bu bölümde de listelenmiştir):

OpenPay webhook'ları imzalamaz; bu nedenle modül bildirimin kendisine asla güvenmez. Bildirimi yalnızca tahsilatı bulmak için kullanır, ardından tahsilatı ödemenin yapıldığı modun ve hesap ülkesinin özel anahtarıyla OpenPay API'sinden okur. Bu mağazanın oluşturmadığı bir tahsilat için gelen bildirim yok sayılır. Webhook, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez.

Gelişmiş

Debug log: ödeme adımlarını modül klasöründeki logs/wc_opy_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar kapalıyken de kaydedilir. Anahtarlar, kart verileri ve müşteri ayrıntıları asla kaydedilmez. 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ırmak, ağ geçidi ayarlarını, kayıtlı webhook doğrulama kodunu ve günlükleri siler. Siparişlerin OpenPay tahsilat kayıtları ödeme geçmişidir ve her zaman saklanır; böylece yeniden kurulumdan sonra da siparişler iade edilebilir. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Credit or debit card (OpenPay)) ve Cardholder name, Card number, Expiry (MM/YY) ve Card code (CVV) alanlarını doldurur. Sandbox modunda form SANDBOX MODE — Test environment. No real charges will be made. mesajını gösterir. Müşteri onayladığında openpay.js kartı tarayıcıda tek kullanımlık bir jetona dönüştürür ve dolandırıcılık kütüphanesi bir cihaz oturum kimliği ekler. Mağazanıza yalnızca bu iki değer ve sepet numarası gönderilir. Form eksikse formun altında Please fill in all card fields. görünür.

Modül ardından sepet toplamı için sepet para biriminde 3D Secure ile tahsilat oluşturur ve müşteriyi OpenPay tarafından sunulan bankasının 3D Secure sayfasına yönlendirir. Her deneme kendi OpenPay sipariş referansını alır. Tahsilat açıklaması Cart #, sepet numarası ve mağazanızın adıdır. Müşterinin adı, e-postası ve telefonu OpenPay'e iletilir; OpenPay'de müşteri hesabı oluşturulmaz. Bu noktada henüz sipariş yoktur.

Müşteri geri döndüğünde modül tahsilatı OpenPay API'sinden okur. Sipariş yalnızca OpenPay onayladıktan sonra ödenmiş olarak işaretlenir: tahsilat bu sepete ait olmalı, tamamlanmış olmalı ve sepet toplamı ile para birimiyle tam olarak eşleşmelidir. Ardından sipariş oluşturulur ve müşteri Your card payment has been received. mesajıyla sipariş onay sayfasını görür. OpenPay tahsilatı devam eden olarak bildirirse sipariş Awaiting OpenPay payment durumunda oluşturulur ve sayfa We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. mesajını gösterir. Sonuç henüz bilinmiyorsa, aynı metni, Check again düğmesi ve Back to checkout düğmesi ile gösteren bir Payment confirmation sayfası açılır; webhook geldiği anda siparişi oluşturur. Devam eden bir tahsilat daha sonra başarısız olursa sipariş onay sayfası Your OpenPay card payment was not completed. Please contact us about this order. mesajını gösterir.

Kart reddedilir veya 3D Secure başarısız olursa müşteri The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. mesajıyla ödeme sayfasına döner ve yeniden ödeyebilir. Sepet korunur. Yeni bir denemeden önce modül sepetin önceki tahsilatını kontrol eder: gerçekten ödenmişse sipariş, ikinci bir tahsilat yapılmadan bundan oluşturulur; hâlâ devam ediyorsa sipariş Awaiting OpenPay payment durumunda oluşturulur; durumu kontrol edilemiyorsa yeni tahsilat yapılmaz ve müşteri We could not confirm the status of your previous payment attempt. Please try again in a few minutes. mesajını görür. Siparişi olan bir sepet asla yeniden tahsil edilmez.

Reddedilen kartlar açık bir mesaj alır, örneğin The card has insufficient funds. Please use another card., The card has expired. Please use another card. veya The security code (CVV) is not valid. Please check it and try again. OpenPay'in teknik hataları müşterilere asla gösterilmez; günlüğe gider.

Ödeme ile onayı arasında sepetteki bir kupon geçerliliğini yitirirse, kupon siparişten kaldırılır. Bu durumda müşteri fiyatı indirimle ödediği için sipariş bir notla birlikte OpenPay payment on hold durumuna geçer.

Ödeme yöntemi; kapalıyken, mevcut modun anahtarları eksikken veya sepet para birimi hesap ülkesi tarafından kabul edilmediğinde ödeme sayfasında gizlenir.

Modül yalnızca kart ödemelerini kabul eder ve bunları hemen tahsil eder. Kayıtlı kart, abonelik, faizsiz taksit (MSI) veya taksitli ödeme, kart puanıyla ödeme, nakit, SPEI, PSE veya CoDi ödemesi ve ayrı yetkilendirme ile tahsilat yoktur.

Siparişler ve iadeler

Sipariş durumları

Henüz sipariş yok: müşteri 3D Secure sayfasındadır, ödemeyi tamamlamamıştır veya kart reddedilmiştir. Yalnızca sepet vardır.

Payment accepted: ödeme onaylandı. Ödeme, OpenPay tahsilat ID'si işlem ID'si olarak kaydedilir; bir not tahsilat ID'sini ve modu (canlı veya sandbox) gösterir.

Awaiting OpenPay payment: OpenPay tahsilatı devam eden olarak bildirir (henüz yakalanmadı). Tahsilat tamamlandığında sipariş Payment accepted durumuna, başarısız olursa Payment error durumuna geçer.

OpenPay payment on hold: OpenPay, sepetten farklı bir tutar veya para birimiyle tamamlanmış bir tahsilat bildirir (sipariş ödenmiş sayılmaz, not farkı gösterir), bir kupon kaldırılmıştır veya zaten iptal edilmiş ya da iade edilmiş bir sipariş için ödeme gelmiştir (ödeme kaydedilir). Siparişi kontrol edip işleyin veya ödemeyi OpenPay panelinde iade edin.

Payment error: devam eden bir tahsilat başarısız oldu, iptal edildi veya süresi doldu.

Refunded: tahsilat modül üzerinden tamamen iade edildi.

Zaten ödenmiş bir sipariş için ikinci bir tamamlanmış tahsilat gelirse sipariş değişmez. WARNING ile başlayan bir not, mükerrer tahsilatı OpenPay panelinde iade etmenizi ister.

OpenPay ödeme bloğu

Sipariş sayfasında tahsilat ID'si, tahsilat durumu, ortam ve hesap ülkesi, tahsil edilen tutar ve sipariş toplamı, iade edilen tutar, sandbox ödemeleri için Sandbox rozeti, iade geçmişi ve siparişin OpenPay notes bölümünü içeren bir OpenPay payment bloğu gösterilir.

İadeler

Meksika ve Peru hesapları için: OpenPay payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isterseniz bir neden yazın ve Refund via OpenPay düğmesine tıklayın. Refund this amount through OpenPay? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler, OpenPay'in tahsil ettiği tutara kadar desteklenir. Siparişleri düzenleme yetkisine ihtiyacınız vardır. İade, tahsilatın yapıldığı modun ve hesap ülkesinin anahtarlarıyla gönderilir; bu nedenle o modun anahtarları tanımlı olmalıdır: sandbox siparişlerini hâlâ iade edebiliyorsanız sandbox anahtarlarını tutun. OpenPay iadeyi kabul etmezse blok hatayı gösterir, örneğin OpenPay refund failed: ..., ve hiçbir iade kaydedilmez. Başarılı bir iade, OpenPay iade ID'si ile birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. İadeler yalnızca OpenPay ödemeyi onayladıktan sonra kullanılabilir; tutar uyuşmazlığı nedeniyle OpenPay payment on hold durumundaki bir sipariş modül üzerinden iade edilmez.

OpenPay Colombia, resmi OpenPay eklentilerinde olduğu gibi API üzerinden kart iadelerini desteklemez. Kolombiya tahsilatları için blok iade formu sunmaz; tahsilatı OpenPay panelinde iade edin.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri OpenPay üzerinden para iadesi yapmaz.

OpenPay panelinde yapılan iadeler ve itirazlar webhook ile gelir ve notlara bir kez eklenir. Sipariş durumu ve kredi notları otomatik olarak değişmez. Gerekirse bunları elle güncelleyin.

Lisans anahtarı

Modül, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox OpenPay Gateway lisans bloğu, Modules > Module Manager > VibeFox OpenPay Gateway > Configure sayfasında ayarların üstünde yer alan ilk bloktur. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı gizlenmiş olarak, durumu (örneğin lisansın hangi tarihe kadar geçerli olduğunu 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-openpay 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 yetkisi olan çalışanlar değiştirebilir. Bloğun metinleri, back office dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini söyler, örneğin Key not found, This key belongs to another product, Domain limit reached veya tarihiyle 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 OpenPay, ö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 back office'e 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 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 sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum, back office'te çalışırken otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonra haftada bir kez. Cron işi gerekmez. Modülün kaldırılması veya sıfırlanması lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

OpenPay ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu ve mevcut modun üç anahtarının da dolu olduğunu kontrol edin: sandbox modundayken sandbox anahtarları, canlı modda canlı anahtarlar. Sepet para biriminin Account country tarafından kabul edildiğini kontrol edin (Meksika: MXN, USD; Kolombiya: COP, USD; Peru: PEN, USD). Ayarlar sayfası bu durumların her birinde bir uyarı gösterir. Payment > Preferences bölümünde modülün sepet para birimi, müşterinin ülkesi ve müşteri grubu için izinli olduğunu kontrol edin.

Ödeme gerçekleşti ama sipariş oluşturulmadı: müşteri 3D Secure sayfasından dönmedi ve webhook çalışmıyor. Kullandığınız modun OpenPay panelinde webhook URL'sinin, ayarların gösterdiği gibi ve yukarıda listelenen olaylarla eklendiğini kontrol edin. Ödemenin yapıldığı modun anahtarlarının dolu olduğunu kontrol edin: bunlar olmadan webhook not configured yanıtı verir ve OpenPay daha sonra yeniden dener. Sipariş ayrıca müşteri mağazaya döndüğünde veya aynı sepeti yeniden ödemeye çalıştığında da oluşturulur.

Webhook ignored (unknown order) yanıtı veriyor: tahsilat bu mağaza tarafından oluşturulmadı; örneğin aynı OpenPay hesabındaki başka bir mağazanın tahsilatı. Hiçbir şey değişmez.

Webhook verification failed yanıtı veriyor: tahsilatı okumak için OpenPay API'sine ulaşılamadı. OpenPay webhook'u yeniden dener.

Webhook busy yanıtı veriyor: sepet aynı anda başka bir istek tarafından güncelleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). OpenPay webhook'u yeniden dener. Nedenini görmek için Debug log seçeneğini açın.

Müşteri The secure card form could not be loaded mesajını görüyor: openpay.js veya OpenPay'in dolandırıcılık kütüphanesi tarayıcıda yüklenemedi ya da cihaz oturum kimliği oluşturulamadı. Müşteriden sayfayı yenilemesini ve yeniden denemesini isteyin.

Müşteri The payment could not be processed right now mesajını görüyor: OpenPay isteği reddetti veya yanıt vermedi. Neden günlükte yazılıdır. Yanlış bir Merchant ID veya özel anahtar tipik bir nedendir. OpenPay yanıt vermediyse müşteri yeniden ödemeden önce OpenPay panelinde tahsilatı kontrol edin.

Müşteri This test card cannot be used for real payments mesajını görüyor: sandbox modu kapalıyken bir sandbox test kartı kullanıldı.

Ödemeden sonra sipariş OpenPay payment on hold durumunda: bloktaki OpenPay notes bölümünü okuyun (bkz. Sipariş durumları), ardından siparişi işleyin veya ödemeyi iade edin.

İade, mod ile ilgili bir mesajla başarısız oluyor: sipariş sandbox veya canlı modda ödenmiş ve o modun anahtarları tanımlı değil. Anahtarları girin ve yeniden deneyin.

İade The order is being updated right now mesajıyla başarısız oluyor: bir webhook veya başka bir istek siparişi aynı anda güncelliyordu. Birazdan yeniden deneyin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox OpenPay Gateway 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ı, kayıtlı webhook doğrulama kodu ve günlükler silinir. Kapalıysa, ileride yeniden kurulum için tüm ayarlar korunur. Siparişlerin OpenPay tahsilat ve iade kayıtları ile Awaiting OpenPay payment ve OpenPay payment on hold sipariş durumları her zaman korunur; böylece daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem ID'lerini korur.

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