VibeFox HyperPay for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

HyperPay hesabı: Satıcı hesabınız kurulduğunda HyperPay Access Token ve Entity ID bilgilerini verir. Test ve canlı kimlik bilgileri farklıdır. Ayrıca HyperPay panelinde bir ödeme webhook'una ve bunun şifre çözme anahtarına (webhook key) ihtiyacınız vardır; anahtar Administration > Webhooks altında gösterilir (bkz. Yapılandırma).

Kart verisi: kart yalnızca HyperPay widget'ına girilir; bu yüzden kart verisi hiçbir zaman sunucunuza ulaşmaz (PCI DSS SAQ A).

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

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. wcp_hyperpay_payment_gateway 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 > HyperPay > 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. HyperPay'in verdiği test Access Token, Entity ID ve webhook anahtarını girin ve Test Mode seçeneğini açık bırakın.

6. HyperPay panelinde (Administration > Webhooks) ayarlarda gösterilen URL ile bir ödeme webhook'u ekleyin ve şifre çözme anahtarını aynı modun webhook anahtarı alanına kopyalayın.

7. Enable/Disable seçeneğini açın ve bir HyperPay test kartıyla test ödemesi yapın. Ardından canlı kimlik bilgilerini girin ve Test Mode seçeneğini kapatın.

Yapılandırma

Tüm ayarlar tek bir sayfadadır: WooCommerce > Settings > Payments > HyperPay. Alanların üstünde sayfa, test modu açıkken Test modu açık: ödemeler HyperPay test sistemine gider ve gerçek para tahsil edilmez. mesajını gösterir. Geçerli modun Access Token veya Entity ID bilgisi eksikse (bu durumda ödeme yöntemi ödeme sayfasında gösterilmez) ve geçerli modda geçerli bir webhook anahtarı yoksa (bu durumda ödemeler yalnızca müşteri mağazaya döndüğünde onaylanır) uyarır. Ödeme yöntemleri listesinde, geçerli modun Access Token ve Entity ID bilgileri girilene kadar ağ geçidi kurulum gerektiriyor olarak işaretlenir. Kaydettiğinizde kimlik bilgilerindeki boşluklar silinir; webhook anahtarı 64 karakterlik onaltılık bir anahtar değilse sayfa hata gösterir.

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

Title: müşterinin ödeme sırasında gördüğü başlık. Varsayılan: Credit/Debit Card (HyperPay).

Description: müşterinin ödeme sırasında gördüğü açıklama. Varsayılan: Pay securely using your credit or debit card.

API kimlik bilgileri

Access Token, Entity ID ve webhook anahtarı, satıcı hesabınız kurulduğunda HyperPay tarafından verilir. Test ve canlı kimlik bilgileri farklıdır. Webhook anahtarı HyperPay panelinde Administration > Webhooks altında gösterilir.

Test Mode: Enable Test Mode HyperPay test sistemini (eu-test.oppwa.com) ve test kimlik bilgilerini kullanır. Gerçek para tahsil edilmez. Gerçek ödemeleri canlı kimlik bilgileriyle (eu-prod.oppwa.com) kabul etmek için kapatın. Varsayılan: açık.

Test Access Token: HyperPay test hesabınızın bearer token'ı.

Test Entity ID: test ödeme kanalının Entity ID'si.

Test Webhook Key: test sisteminin webhook bildirimlerini çözmek için kullanılan 64 karakterlik onaltılık anahtar.

Live Access Token: HyperPay canlı hesabınızın bearer token'ı.

Live Entity ID: canlı ödeme kanalının Entity ID'si.

Live Webhook Key: canlı sistemin webhook bildirimlerini çözmek için kullanılan 64 karakterlik onaltılık anahtar.

Webhook

Webhook, müşteri mağazaya dönmeden tarayıcıyı kapatsa bile mağazanıza ödemeler hakkında bilgi verir. HyperPay panelinde (Administration > Webhooks) ayarların bu bölümünde gösterilen URL ile ödemeler için bir webhook ekleyin. URL şu biçimdedir: https://your-site/wp-json/hyperpay-p/v1/webhook. Ardından webhook şifre çözme anahtarını aynı mod için Test Webhook Key veya Live Webhook Key alanına kopyalayın.

HyperPay webhook'ları şifrelidir (AES-256-GCM). Anahtarlarınızla şifresi çözülemeyen bir webhook reddedilir. Yalnızca ödeme bildirimleri işlenir ve ödeme, bildirimin şifresini çözen anahtarla aynı modda oluşturulmuş, sizin siparişlerinizden birinin ödeme oturumuna ait olmalıdır. HyperPay test bildirimleri onaylanır. Webhook ayrıca HyperPay panelinde yapılan tahsilatları, reversal'ları, iadeleri ve chargeback'leri de bildirir (bkz. Siparişler ve iadeler). Webhook yoksa bir ödeme, müşteri ödemeden sonra mağazaya dönene kadar onaylanmaz.

Ödeme

Transaction Type: kartın nasıl tahsil edileceği.

Payment Brands: ödeme widget'ında gösterilen markalar: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Varsayılan: VISA ve Mastercard. Yalnızca HyperPay'in Entity ID'niz için etkinleştirdiği markaları seçin; mada, STC Pay ve Apple Pay genellikle kendi varlığını kullanır ve bu eklenti bunu desteklemez.

Gelişmiş

Enable Logging: Log API requests and responses. Hata ayıklama bilgileri WooCommerce > Status > Logs içine, kaynak wcp_hyperpay_payment_gateway olarak yazılır. Hatalar her zaman kaydedilir. Günlükler kart verisi, anahtar veya müşteri verisi içermez. Varsayılan: kapalı.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Eklenti silindiğinde ayarları ve günlük dosyalarını kaldırır. Siparişlerde saklanan HyperPay verileri korunur. Varsayılan: kapalı.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Credit/Debit Card (HyperPay)) ve Continue to payment düğmesine tıklar. Sipariş oluşturulur ve müşteri Pay for order sayfasına gider. Orada eklenti, sipariş toplamı için sipariş para biriminde bir HyperPay ödeme oturumu hazırlar ve HyperPay widget'ını Lütfen ödemenizi aşağıdan tamamlayın: mesajıyla gösterir. Widget, HyperPay destekliyorsa sitenizin dilini kullanır. Test modunda sayfa Test modu: HyperPay test kartı kullanın, gerçek ödeme yapılmayacaktır. mesajını gösterir. Müşteri kart bilgilerini widget'a girer.

Ödemeden sonra müşteri mağazanıza döner. Eklenti, ödemenin bu siparişin ödeme oturumlarından birine ait olduğunu kontrol eder ve HyperPay'den sunucudan sunucuya bir istekle sonucu sorar. Sipariş, HyperPay onaylayana kadar ödenmiş olarak işaretlenmez: bu istek veya webhook ile. Tutar ve para birimi siparişle eşleşmelidir. Aynı anda gelen bir dönüş ve bir webhook sırayla işlenir, bu yüzden sipariş asla iki kez işlenmez. Ödeme onaylandığında müşteri sipariş alındı sayfasına yönlendirilir.

Ödeme gerçekleşmediyse müşteri Pay for order sayfasına döner ve bir mesaj görür: Ödeme başarısız: ardından HyperPay'in belirttiği neden, Ödeme tamamlanmadı. Lütfen tekrar deneyin. ya da Ödemeniz henüz onaylanamadı. Ücret tahsil edildiyse sipariş otomatik olarak güncellenecektir; aksi halde lütfen tekrar deneyin. Müşteri aynı sayfada yeniden ödeme yapabilir. Widget hazırlanamazsa müşteri kısa bir mesaj görür; örneğin bazı fatura bilgilerinin ödeme sağlayıcısı tarafından kabul edilmediğini belirten bir mesaj ve bir Try Again düğmesi. Ayrıntılar sipariş notlarına eklenir.

Tutarlar, HyperPay API'sinin gerektirdiği gibi iki ondalık basamakla gönderilir. 3 ondalık basamaklı para birimlerinde (KWD, BHD, JOD, OMR) sipariş toplamı iki ondalık basamağa yuvarlanır.

Ödeme yöntemi klasik ödeme sayfasında, Sepet ve Ödeme bloklarında ve Pay for order sayfasında çalışır. Test modunda Ödeme bloğu Test modu: gerçek ödeme yapılmayacaktır. mesajını gösterir. WooCommerce High-Performance Order Storage (HPOS) ile uyumludur.

Eklenti, WooCommerce üzerinden iade veya iptal, kayıtlı kart veya tokenizasyon, abonelik, Apple Pay alan adı doğrulaması, marka başına ayrı Entity ID ve Tabby, Tamara veya diğer "şimdi al, sonra öde" (buy-now-pay-later) yöntemlerini desteklemez.

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri henüz ödeme yapmadı, widget'ı tamamlamadı veya HyperPay ödemeyi henüz onaylamadı.

Processing: bir tahsilat ödemesi onaylandı veya bir ön provizyon tahsil edildi. Yalnızca sanal indirilebilir ürün içeren siparişler, WooCommerce varsayılanı olarak Tamamlandı durumuna geçer. Sipariş notu HyperPay sonuç kodunu, açıklamasını ve ödeme kimliğini gösterir. İşlem kimliği HyperPay ödeme kimliğidir. HyperPay ödemeyi manuel inceleme için işaretlediyse not bunu belirtir; kargolamadan önce HyperPay panelinde kontrol edin.

On hold (pre-authorization): tutar ayrıldı. Capture HyperPay payment sipariş işlemiyle ya da HyperPay panelinde tahsil edin; tahsilat webhook'u siparişi tamamlar.

On hold after payment: HyperPay, siparişten farklı bir tutar veya para birimi bildirdi (örneğin ödeme sayfası açıldıktan sonra sipariş düzenlendiyse), ödeme HyperPay'de hâlâ beklemede veya ödeme, sipariş iptal edildikten sonra geldi. Sipariş notu bunu açıklar. HyperPay panelinde ödemeyi kontrol edin ve tamamlayın ya da iade edin.

Failed: HyperPay ödemeyi reddetti. Nedeni sipariş notunda yer alır ve müşteriye gösterilir. Reddedilen bir deneme, zaten ödenmiş, ayrılmış, beklemede veya iptal edilmiş bir siparişi asla değiştirmez.

Cancelled: bir ön provizyon HyperPay panelinde iptal edildi ve iptal (reversal) webhook'u beklemedeki siparişi iptal eder.

Zaten ödenmiş bir sipariş için başka bir başarılı ödeme gelirse sipariş değişmez. Bir not, mükerrer ödemeyi HyperPay panelinden iade etmenizi ister. İade edilmiş bir sipariş için gelen başarılı bir ödeme yalnızca bir not ekler.

Tahsilat

Capture HyperPay payment sipariş işlemi, henüz tahsil edilmemiş bir ön provizyonu olan beklemedeki siparişlerde görünür. Bu işlem, ön provizyonun yapıldığı modda, WooCommerce'te zaten kaydedilmiş iadeler düşüldükten sonra geçerli sipariş toplamını tahsil eder. Başarılı bir tahsilattan sonra sipariş Processing durumuna geçer. HyperPay tahsilatı reddederse sonuç kodu ve açıklama gösterilir ve sipariş notlarına eklenir. Ön provizyonun iptali (void) HyperPay panelinde yapılır.

İadeler

WooCommerce'ten iade desteklenmez. Ödemeyi HyperPay panelinde iade edin ve WooCommerce'te Refund manually ile kaydedin. HyperPay'de yapılan iadeler ve chargeback'ler webhook ile siparişe not olarak eklenir; sipariş durumu değişmez.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Payments > HyperPay 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 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 tek bir alan adında çalışır. Anahtarı bir siteden kaldırmak, o alan adının yuvasını boşaltmaz. Yuvayı vibefox.net hesabınızdan boşaltın.

Etkin bir anahtar yoksa HyperPay, ödeme sırasında müşterilere gösterilmez. Yine de bir ödeme başlatılırsa müşteri Bu ödeme yöntemi kullanılamıyor. Lütfen başka bir yöntem seçin. mesajını görür. Oturum açmış mağaza yöneticileri ödeme yöntemini (unlicensed — visible to admins only) işaretiyle görmeye devam eder; böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirler. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: başlatılmış ödemeler onaylanmaya devam eder ve tahsilatlar çalışır.

Lisansın 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

HyperPay ö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 Access Token ve Entity ID bilgilerine sahip olduğunu kontrol edin: test modunda test bilgileri, canlı modda canlı bilgiler. Ayarlar sayfası eksik olduğunda uyarı gösterir.

Ödeme gerçekleşti, ancak sipariş Pending payment durumunda kalıyor: webhook çalışmıyor ve müşteri mağazaya dönmedi. HyperPay panelinde, kullandığınız mod için ödeme webhook'unun var olduğunu, URL'sinin ayarlarda gösterilenle tam olarak aynı olduğunu ve şifre çözme anahtarının aynı modun webhook anahtarı alanında bulunduğunu kontrol edin. WooCommerce > Status > Logs sayfasına, kaynak wcp_hyperpay_payment_gateway olacak şekilde bakın.

Webhook Decryption failed yanıtı veriyor: webhook anahtarı başka bir webhook'a veya başka bir moda ait. Anahtarı HyperPay panelinden yeniden kopyalayın.

Webhook Webhook key not configured yanıtı veriyor: geçerli bir webhook anahtarı ayarlanmamış. 64 karakterlik anahtarı ayarlara yapıştırın. HyperPay webhook'u yeniden dener.

Günlükte Webhook ignored görünüyor: ödeme bu mağazanın bir siparişine ait değil veya diğer modda yapılmış. Test ve canlı ödemeler birbirinden ayrı tutulur.

Ödeme formu yüklenmiyor: sipariş notunu okuyun. Yapılandırma hatası genellikle geçerli mod için yanlış bir Access Token veya Entity ID anlamına gelir. Fatura bilgileriyle ilgili bir mesaj, HyperPay'in bazı müşteri verilerini kabul etmediği anlamına gelir. Seçili Payment Brands seçeneklerinin Entity ID'niz için etkin olduğundan emin olun.

Sipariş On hold durumunda ve tutar/para birimi uyuşmazlığı notu var: HyperPay, sipariş toplamı veya para birimiyle eşleşmeyen bir ödeme bildirdi; örneğin ödeme sayfası açıldıktan sonra sipariş düzenlendiği için. HyperPay panelinde ödemeyi kontrol edin ve tamamlayın ya da iade edin.

Tahsilat başarısız oluyor: sipariş notundaki sonuç kodunu ve açıklamayı okuyun. Tahsilat, ön provizyonun modunda gönderilir; bu yüzden o modun kimlik bilgilerinin girilmiş olması gerekir.

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 yuva boşaltı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.

Geliştiriciler için: hyperpay_p_icon filtresi ödeme yöntemi simgesini değiştirir.

Kaldırma

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

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