VibeFox OpenPay for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

WooCommerce: 8.0 veya üzeri, kurulu ve etkin. Eklenti WooCommerce olmadan etkinleştirilmez.

PHP: 8.0 veya üzeri.

HTTPS: Kart formu ödeme sayfanızda olduğu için sitenizin HTTPS kullanması gerekir.

OpenPay hesabı: Meksika, Kolombiya veya Peru'ya ait bir OpenPay hesabı. Bu hesabın Merchant ID'si, özel anahtarı (sk_...) ve genel anahtarı (pk_...) gereklidir. Sandbox ve canlı panellerin Merchant ID ve anahtarları farklıdır; eklenti bunları ayrı tutar.

VibeFox lisans anahtarı: vibefox.net üzerinden 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 jetona dönüştürülür. Kart alanlarının adı yoktur ve hiçbir zaman sunucunuza gönderilmez. Kart formu sayfanızda olduğu için PCI DSS kapsamınız SAQ A-EP'dir; bunu acquirer kuruluşunuza danışın.

Kurulum

1. WordPress'te Plugins > Add New > Upload Plugin yolunu izleyin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Alternatif olarak wcp_openpay_gateway klasörünü FTP ile /wp-content/plugins/ dizinine yükleyebilirsiniz.

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

3. Ayarları açın: WooCommerce > Settings > Payments > OpenPay > Manage ya da Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

4. Sayfanın üstündeki lisans bloğuna VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın.

5. Account country seçeneğini belirleyin ve sandbox ile canlı anahtarları girin (bkz. Yapılandırma).

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

7. Enable / Disable seçeneğini etkinleştirin ve kaydedin. OpenPay sandbox test kartlarıyla bir ödeme deneyin, ardından gerçek ödemeleri kabul etmek için Sandbox mode seçeneğinin işaretini kaldırın.

Yapılandırma

Tüm ayarlar tek bir sayfada bulunur: WooCommerce > Settings > Payments > OpenPay. Alanların üzerinde sayfa, geçerli modun anahtarları eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir), mağaza para birimi seçilen hesap ülkesi tarafından kabul edilmiyorsa sizi uyarır ve sandbox modu açıkken Sandbox mode is enabled — no real charges are made. mesajını gösterir. Ödeme yöntemleri listesinde, geçerli mod üç anahtarın tamamına sahip olana kadar OpenPay kurulum gerektiren olarak işaretlenir; sandbox modu açık olduğu sürece bir test modu rozeti gösterilir.

Kaydettiğinizde anahtarlar doğrulanır. Merchant ID yalnızca harf ve rakam içerebilir; özel anahtar sk_, genel anahtar pk_ ile başlamalıdır. Geçersiz bir değer kaydedilmez: önceki değer korunur ve Sandbox: The private key must start with sk_. gibi bir hata gösterilir. Ödeme yöntemi etkinse ancak geçerli modun anahtarları eksikse, ağ geçidinin ödeme sayfasında gizli kalacağını bildiren bir mesaj da görürsünüz.

Genel

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ı. Varsayılan: Credit or debit card (OpenPay).

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. Bu bölümde Meksika, Kolombiya ve Peru için sandbox ve canlı panellere bağlantılar yer alı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: Use the OpenPay sandbox (test keys, no real charges) 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 kabul etmek için işaretini kaldırı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ı panelindeki Merchant ID, Settings (Configuración), API anahtarları.

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

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

Eklentinin 1.0 sürümündeki anahtarlar (tek bir anahtar seti ve bir sandbox bayrağı) otomatik olarak sandbox veya canlı alanlarına taşınır.

Webhook

Webhook zorunlu değildir, ancak önerilir. Müşteri 3D Secure sayfasından geri dönmediğinde, örneğin tarayıcıyı kapattığında ödemeleri onaylar. OpenPay panelinde Settings > Webhooks bölümüne gidin ve ayarların bu kısmında gösterilen URL'yi ekleyin. Şuna benzer: https://your-site/wc-api/webhook_wc_openpay/. Ayarlarda gösterildiği gibi aynen kopyalayın. Kullandığınız her modun panelinde (sandbox ve canlı) webhook'u ekleyin.

Webhook'u 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:

OpenPay webhook'ları imzalamaz; bu nedenle eklenti bildirimin kendisine asla güvenmez. Bildirimi yalnızca tahsilatı bulmak için kullanır, ardından tahsilatı siparişin ödendiği modun özel anahtarıyla OpenPay API'sinden okur. Bu mağazanın oluşturmadığı bir tahsilata ait bildirim yok sayılır.

Gelişmiş

Debug log: Log payment steps (errors are always logged) ödeme adımlarını WooCommerce > Status > Logs içine, wcp_openpay_gateway kaynağıyla yazar. Hatalar ve uyarılar bu seçenek kapalıyken de kaydedilir. Anahtarlar, kart verileri ve müşteri bilgileri asla günlüğe yazılmaz. Varsayılan: kapalı.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Varsayılan: kapalı.

Ödeme sayfası

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. Sipariş verildiğinde openpay.js kartı tarayıcıda tek kullanımlık bir jetona dönüştürür ve OpenPay'in antifraud kitaplığı bir cihaz oturum kimliği ekler. Mağazanıza yalnızca bu iki değer gönderilir.

Eklenti ardından sipariş toplamı için sipariş 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 OpenPay'de kendi sipariş referansını alır (sipariş numarası ve kısa bir son ek). Tahsilat açıklaması Order #, sipariş numarası ve site adınızdır. Müşterinin adı, e-posta adresi ve telefonu OpenPay'e iletilir; OpenPay'de müşteri hesabı oluşturulmaz. Müşteri 3D Secure sayfasındayken sipariş Ödeme bekleniyor durumunda kalır.

Müşteri geri döndüğünde eklenti tahsilatı OpenPay API'sinden okur. Sipariş, OpenPay onaylayana kadar ödenmiş olarak işaretlenmez: tahsilat bu siparişe ait olmalı, tamamlanmış olmalı ve siparişin toplamı ile para birimiyle birebir eşleşmelidir. Sonuç henüz bilinmiyorsa sipariş alındı sayfasında We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. mesajı gösterilir. Ardından webhook siparişi günceller.

Kart reddedilir veya 3D Secure başarısız olursa müşteri Pay for order sayfasına, The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. mesajıyla döner ve yeniden ödeyebilir. Yeni bir denemeden önce eklenti siparişin önceki tahsilatını kontrol eder: gerçekten ödenmişse, ikinci bir tahsilat yapılmadan sipariş ödenmiş olarak işaretlenir; hâlâ işleniyorsa müşteri önceki bir ödemenin hâlâ işlendiğini görür ve tekrar ödeme yapmamalıdır; durumu kontrol edilemiyorsa yeni bir deneme yapılmaz ve müşteriden birkaç dakika sonra yeniden denemesi istenir.

Reddedilen kartlara açık bir mesaj gösterilir, ö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; sipariş notlarına ve günlüğe gider.

Ödeme yöntemi klasik ödeme sayfasında, Checkout bloğunda ve Pay for order sayfasında çalışır. WooCommerce High-Performance Order Storage (HPOS) ile uyumludur. Devre dışıyken, geçerli modun anahtarları eksikken veya sipariş para birimi hesap ülkesi tarafından kabul edilmiyorsa ödeme sayfasında gizlenir.

Eklenti yalnızca kart ödemelerini, hemen tahsilatla kabul 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 desteklenmez.

Siparişler ve iadeler

Sipariş durumları

Ödeme bekleniyor: müşteri 3D Secure sayfasındadır veya ödemeyi tamamlamamıştır. Bir not tahsilat kimliğini gösterir.

İşleniyor: ödeme onaylandı. Bu, ödeme sonrası WooCommerce'in standart durumudur; yalnızca sanal, indirilebilir ürün içeren siparişler Tamamlandı olur. Sipariş notu tahsilat kimliğini ve modu (canlı veya sandbox) gösterir. İşlem kimliği OpenPay tahsilat kimliğidir.

Beklemede: tahsilat devam ediyor ve henüz yakalanmadı; ya da OpenPay, siparişten farklı bir tutar veya para birimiyle tamamlanmış bir tahsilat bildiriyor (sipariş ödenmiş olarak işaretlenmez, not farkı gösterir); ya da zaten iptal edilmiş bir sipariş için ödeme geldi. Siparişi OpenPay panelinde kontrol edin ve oradan tamamlayın veya ödemeyi iade edin.

Başarısız: tahsilat oluşturulurken kart reddedildi ya da son deneme başarısız oldu, iptal edildi veya süresi doldu. Müşteri tekrar ödeme yapabilir.

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.

İadeler

Meksika ve Peru hesapları için: siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Credit or debit card (OpenPay) düğmesine tıklayın (düğme ödeme yönteminizin başlığını gösterir). Tam ve kısmi iadeler desteklenir. İade, siparişin ödendiği mod ve hesap ülkesiyle gönderilir; bu nedenle iade edilecek sandbox siparişleriniz varken sandbox anahtarlarını dolu tutun. OpenPay iadeyi kabul etmezse WooCommerce hatayı gösterir, örneğin OpenPay refund failed: ..., ve hiçbir iade kaydedilmez. Başarılı bir iade, OpenPay iade kimliğiyle birlikte sipariş notlarına eklenir.

OpenPay Colombia, resmi OpenPay eklentilerinde olduğu gibi API üzerinden kart iadesini desteklemez. Kolombiya için iade düğmesi sunulmaz; tahsilatı OpenPay panelinden iade edin.

OpenPay panelinde yapılan iadeler ve itirazlar webhook ile gelir ve sipariş notlarına bir kez eklenir. Otomatik olarak WooCommerce iadesi olarak kaydedilmezler. Gerekirse OpenPay düğmesini kullanmadan WooCommerce'te manuel bir iade oluşturun.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Payments > OpenPay sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blok durumu gösterir; örneğin lisansın geçerli olduğu son tarihi ve alan adınızı. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key, 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ın bir siteden kaldırılması alan adı kotasını serbest bırakmaz. Kotayı 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. Oturum açmış mağaza yöneticileri ödeme yöntemini (unlicensed — visible to admins only) etiketiyle görmeye devam eder; böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: başlatılmış ödemeler yine onaylanır, iadeler çalışmaya devam eder.

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

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 geçerli modun üç anahtarının da bulunduğunu kontrol edin: sandbox modunda sandbox anahtarları, canlı modda canlı anahtarlar. Mağaza para biriminin Account country tarafından kabul edildiğini kontrol edin (Meksika: MXN, USD; Kolombiya: COP, USD; Peru: PEN, USD). Ayarlar sayfası her durumda bir uyarı gösterir.

Ödeme geçti ama sipariş Ödeme bekleniyor durumunda kaldı: müşteri 3D Secure sayfasından geri dönmedi ve webhook çalışmıyor. Kullandığınız modun OpenPay panelinde webhook URL'sinin, ayarlarda gösterildiği gibi ve yukarıda listelenen olaylarla eklendiğini kontrol edin. Siparişin ödendiği modun anahtarlarının girildiğini kontrol edin: anahtarlar olmadan webhook not configured yanıtı verir ve OpenPay daha sonra yeniden dener.

Webhook ignored (unknown order) yanıtı veriyor: tahsilat, bu mağaza tarafından bu sipariş için oluşturulmamış; ö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: sipariş aynı anda başka bir istek tarafından güncelleniyordu. OpenPay webhook'u yeniden dener.

Müşteri «The secure card form could not be loaded» mesajını görüyor: openpay.js veya OpenPay'in antifraud kitaplığı 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. Nedeni sipariş notlarında ve wcp_openpay_gateway kaynağıyla günlükte bulunur. Yanlış bir Merchant ID veya özel anahtar tipik bir nedendir. OpenPay yanıt vermediyse, müşteri tekrar ödeme yapmadan önce OpenPay panelinde tahsilatı kontrol edin.

«This test card cannot be used for real payments»: sandbox modu kapalıyken bir sandbox test kartı kullanıldı.

Ödemeden sonra sipariş Beklemede: sipariş notunu okuyun. Tahsilat hâlâ devam ediyor, ödenen tutar veya para birimi siparişle uyuşmuyor ya da ödeme siparişin iptalinden sonra geldi.

İade, mod ile ilgili bir mesajla başarısız oluyor: sipariş sandbox veya canlı modda ödenmiş ve o modun anahtarları girilmemiş. Anahtarları girin ve tekrar deneyin.

Lisans bloğu bir hata gösteriyor: bloktaki mesajı izleyin. Örneğin anahtar başka bir alan adında zaten kullanılıyorsa vibefox.net hesabınızda bir kota serbest bırakın ve Check now düğmesine tıklayın. Site adresi değiştiyse yeni alan adı için anahtarı 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. Kaldırmak için eklentiyi Plugins sayfasından devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman silinir. Ağ geçidi ayarları, saklanan webhook doğrulama kodu ve eklentinin günlükleri yalnızca Delete data on uninstall açıksa silinir. Aksi halde sonraki bir yeniden kurulum için saklanır. Sipariş verileri her zaman korunur: mevcut siparişler ödeme notlarını, işlem kimliklerini ve yeniden kurulumdan sonra iadeler için gereken tahsilat verilerini saklar.

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