VibeFox HyperPay for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

PHP: OpenSSL uzantısıyla birlikte 8.0 veya üzeri (webhook'ları şifre çözmek için kullanılır). Bu uzantı olmadan modül kurulamaz.

HyperPay hesabı: HyperPay, satıcı hesabınız kurulduğunda 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 nedenle 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. Back office'te 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 tamamlandığında Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox HyperPay Payment Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. 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.

5. HyperPay panelinde (Administration > Webhooks) Webhook bölümündeki URL ile bir ödeme webhook'u ekleyin ve şifre çözme anahtarını aynı modun webhook anahtarı alanına kopyalayın.

6. Enable/Disable seçeneğini açın, Save düğmesine tıklayın ve bir HyperPay test kartıyla deneme ödemesi yapın. Ardından canlı kimlik bilgilerini girin ve Test Mode seçeneğini kapatın.

Kurulumda modül üç sipariş durumu oluşturur: Awaiting HyperPay payment, HyperPay payment authorized ve HyperPay payment on hold. PrestaShop, yeni bir ödeme modülünü o anda aktif olan para birimleri, ülkeler ve müşteri gruplarıyla ilişkilendirir. Daha sonra etkinleştirdiğiniz ülkelerin Payment > Preferences bölümünde izin verilmesi gerekir.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox HyperPay Payment 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, test modu açıkken Test mode is on: payments go to the HyperPay test system and no real money is charged. mesajını gösterir. Geçerli modun Access Token veya Entity ID bilgisi eksikse uyarır (bu durumda ödeme yöntemi ödeme sayfasında gösterilmez); geçerli modun geçerli bir webhook anahtarı yoksa da uyarır (bu durumda ödemeler yalnızca müşteri mağazaya döndüğünde onaylanır). Kaydettiğinizde kimlik bilgilerindeki boşluklar silinir ve bir webhook anahtarı 64 karakterlik onaltılık bir anahtar değilse sayfa uyarır.

HyperPay

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

Title: müşterinin ödeme sayfasında gördüğü başlık. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Credit/Debit Card (HyperPay). Zorunlu.

Description: müşterinin ödeme sayfası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: HyperPay test sistemini (eu-test.oppwa.com) ve test kimlik bilgilerini kullanır. Gerçek para çekilmez. Canlı kimlik bilgileriyle (eu-prod.oppwa.com) gerçek ödemeler almak için kapatın. Varsayılan: açık. Açık olduğu sürece müşteriler ödeme yönteminin altında Test mode: no real payment will be made. mesajını görür.

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 şifresini çö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 şifresini çözmek için kullanılan 64 karakterlik onaltılık anahtar.

Kayıtlı access token'lar ve webhook anahtarları bir daha gösterilmez. Alan boş kalır ve Saved — leave empty to keep it. mesajını gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Kayıtlı gizli bilgileri temizle: bir token veya anahtarı işaretleyip kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

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) bu bölümdeki Webhook URL alanında gösterilen URL ile bir ödeme webhook'u ekleyin. SEO dostu URL'lerle şu biçimde görünür: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. URL'yi ayarların gösterdiği gibi birebir kopyalayın. 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, sepetlerinizden birinin bir ödeme oturumuna ait olmalı ve onu şifreleyen anahtarla aynı modda oluşturulmuş 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 olmadan, bir ödeme yalnızca müşteri ödemeden sonra mağazaya döndüğünde onaylanır.

Payment

Transaction Type: kartın nasıl çekileceği.

Payment Brands: ödeme widget'ında gösterilen markalar: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Varsayılan: VISA ve Mastercard. Hiçbir marka işaretli değilse sayfa uyarır ve widget VISA ile Mastercard'ı gösterir. Yalnızca HyperPay'in Entity ID'niz için etkinleştirdiği markaları seçin; mada, STC Pay ve Apple Pay genellikle kendi entity'lerini kullanır ve bu modül bunları desteklemez.

Advanced

Enable Logging: API isteklerini ve yanıtlarını modül klasöründeki logs/hyperpay_p_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar her zaman kaydedilir. Günlükler kart verisi, anahtar veya müşteri verisi içermez. Varsayılan: kapalı.

Log: günlüğün boyutunu ve en 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ırıldığında ayarlar, HyperPay ödeme denemeleri tablosu ve günlük dosyaları silinir. Siparişler ve modülün sipariş durumları korunur. Varsayılan: kapalı.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Credit/Debit Card (HyperPay)) ve siparişi onaylar. Modül, sepet tutarı ve sepet para birimi için bir HyperPay ödeme oturumu hazırlar ve mağazanızın HyperPay widget'ı ile Please complete your payment below: mesajını içeren HyperPay payment sayfasını açar. HyperPay destekliyorsa widget müşterinin dilini kullanır. Test modunda sayfa Test mode: use a HyperPay test card, no real payment will be made. mesajını gösterir. Müşteri kart bilgilerini widget'a girer veya Choose another payment method bağlantısını izleyerek ödeme sayfasına geri döner. Bu noktada henüz bir sipariş yoktur. Sayfayı yenilemek, sepet değişmediği sürece aynı ödeme oturumunu 25 dakikaya kadar yeniden kullanır.

Ödemeden sonra müşteri mağazanıza döner. Modül, ödemenin bu sepetin bir ödeme oturumuna ait olduğunu doğrular ve sonucu, oturumun oluşturulduğu modda, sunucudan sunucuya bir istekle HyperPay'den ister. Sipariş, yalnızca HyperPay bunu onayladığında (bu istekle veya webhook ile) ödenmiş olarak işaretlenir. Tutar ve para birimi sepetle eşleşmelidir. Dönüş ve bir webhook aynı anda gelirse, bunlar birbiri ardına işlenir; böylece sipariş hiçbir zaman iki kez oluşturulmaz. Ödeme onaylandığında sipariş oluşturulur ve müşteri standart sipariş onay sayfasını görür.

Ödeme tamamlanmadıysa müşteri bir mesajla ödeme sayfasına döner: Payment failed: ve HyperPay'in verdiği neden, Payment was not completed. Please try again. veya We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Sepet korunur ve müşteri yeniden ödeyebilir; her yeni deneme yeni bir HyperPay ödeme oturumu alır. Ödeme formu hazırlanamazsa müşteri ödeme sayfasında kalır ve kısa bir mesaj görür; örneğin bazı fatura bilgilerinin ödeme sağlayıcı tarafından kabul edilmediği ya da bir ödeme yapılandırma hatası nedeniyle ödeme formunun kullanılamadığı bildirilir. Teknik neden günlüğe yazılır.

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

Webhook, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasına takılmaz.

Modül, PrestaShop ü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" yöntemlerini desteklemez.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri ödeme sayfasına yönlendirildi ve ödeme yapmadı, ödeme reddedildi ya da HyperPay ödemeyi henüz onaylamadı. Yalnızca sepet vardır.

Payment accepted: bir Debit ödemesi onaylandı ya da bir ön provizyon tahsil edildi. Ödeme, işlem kimliği olarak HyperPay ödeme kimliğiyle kaydedilir ve özel bir not HyperPay sonuç kodunu, açıklamasını ve ödeme kimliğini gösterir. HyperPay ödemeyi manuel inceleme için işaretlediyse not bunu belirtir; göndermeden önce HyperPay panelinde kontrol edin.

HyperPay payment authorized: tutar bir ön provizyonla ayrılmıştır. Siparişin HyperPay bloğunda veya HyperPay panelinde tahsil edin; tahsilat webhook'u siparişi Payment accepted durumuna taşır.

Awaiting HyperPay payment: HyperPay ödemeyi beklemede olarak bildirdi. HyperPay ödemeyi onayladığında sipariş Payment accepted durumuna geçer.

HyperPay payment on hold: HyperPay, sepetten veya siparişten farklı bir tutar ya da para birimi bildirdi (örneğin ödeme sayfası açıldıktan sonra sepet değiştirildi) ya da ödeme, sipariş iptal edildikten sonra geldi. Not nedenini açıklar. Ödemeyi HyperPay panelinde kontrol edin, ardından siparişi tamamlayın veya ödemeyi iade edin.

Canceled: bir ön provizyon HyperPay panelinde geri alındı ve reversal webhook'u yetkilendirilmiş siparişi iptal eder.

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

HyperPay ödeme bloğu

Sipariş sayfasında ödeme kimliği (tahsilattan sonra tahsilat kimliğiyle birlikte), işlem türü, ödeme oturumu kimliği, satıcı işlem kimliği, HyperPay'e gönderilen tutar, sonuç ve test ödemeleri için bir Test mode rozeti içeren bir HyperPay payment bloğu gösterilir. Modülün notları siparişin özel mesajlarındadır.

Tahsilat

HyperPay payment authorized durumundaki bir sipariş için blokta tutarla birlikte Capture payment görünür. Tıklayın ve Capture the pre-authorized amount through HyperPay? sorusunu onaylayın. Ön provizyonun yapıldığı modda, mevcut sipariş toplamı tahsil edilir; bu nedenle o modun Access Token ve Entity ID bilgileri tanımlı olmalıdır. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modül sayfalarına erişim gerekmez. Başarılı bir tahsilattan sonra sipariş Payment accepted durumuna geçer ve tahsilat kimliği ödemeye ve notlara eklenir. HyperPay tahsilatı reddederse sonuç kodu ve açıklama gösterilir ve notlara eklenir; sipariş yetkili kalır. Çift tıklama tahsilatı iki kez yapmaz. Bir ön provizyonun geri alınması (void) HyperPay panelinde yapılır.

İadeler

PrestaShop'tan iadeler desteklenmez ve PrestaShop'un standart iade düğmeleri HyperPay üzerinden para göndermez. Ödemeyi HyperPay panelinde iade edin ve gerekirse PrestaShop'ta kısmi iade veya kredi notu ile kaydedin. HyperPay'de yapılan iadeler ve chargeback'ler webhook tarafından siparişe not olarak eklenir; sipariş durumu değişmez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox HyperPay Payment Gateway, Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskeli 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-hyperpay satırı ile hesabınızda vibefox.net'i 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 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 HyperPay ö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 sizden de gizlenir: modülü anahtar satın almadan önce kurabilirsiniz, ama ö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 yine onaylanır, tahsilatlar 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 her gün bir kez, sonrasında haftada bir kez. Cron job gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman siler.

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 bilgilerinin bulunduğunu kontrol edin: test modunda test bilgileri, canlı modda canlı bilgiler. Eksikse ayarlar sayfası bir 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 gerçekleşti, ancak sipariş oluşturulmadı: 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 Webhook URL altında gösterilenle birebir aynı olduğunu ve şifre çözme anahtarının aynı modun webhook anahtarı alanında bulunduğunu kontrol edin. Enable Logging seçeneğini açın ve modül sayfasındaki Log alanına 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.

Webhook Busy, retry later yanıtı veriyor: sipariş aynı anda başka bir istek tarafından işleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). HyperPay webhook'u yeniden dener. Nedeni günlükte yazar.

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

Webhook URL'si tarayıcıda Method not allowed gösteriyor: bu normaldir. URL yalnızca HyperPay'den gelen POST isteklerini kabul eder.

Ödeme formu yüklenmiyor: günlüğe bakın. Yapılandırma hatası genellikle geçerli mod için yanlış 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 markalarının Entity ID'niz için etkin olduğundan emin olun.

Sipariş HyperPay payment on hold durumunda: siparişin notlarını okuyun (bkz. Sipariş durumları), ödemeyi HyperPay panelinde kontrol edin, ardından siparişi tamamlayın veya ödemeyi iade edin.

Tahsilat başarısız oluyor: bloktaki ve notlardaki sonuç kodunu ve açıklamayı okuyun. Tahsilat ön provizyonun modunda gönderilir, bu nedenle o modun bilgileri tanımlı olmalıdır; aksi halde blok, o modun Access Token / Entity ID bilgilerinin boş olduğunu belirtir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox HyperPay Payment 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 ayarlar, HyperPay ödeme denemeleri tablosu ve günlük dosyaları silinir. Kapalıysa her şey sonraki bir yeniden kurulum için saklanır. Awaiting HyperPay payment, HyperPay payment authorized ve HyperPay payment on hold sipariş durumları her zaman saklanır. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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