VibeFox Hubtel for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

PHP: cURL uzantılı 8.0 veya üzeri. Bunlar yoksa modül kurulmaz.

Para birimi: Yalnızca Gana cedisi (GHS). Diğer para birimlerinde ödeme yöntemi ödeme sayfasında gizlenir. Hubtel tam pesewa tahsil ettiği için GHS para biriminin ondalık basamak sayısını 2 olarak tutun.

Hubtel hesabı: API anahtarları (API ID ve API Key) ile satıcı hesap numarasına (POS Sales ID) sahip bir Hubtel işletme hesabı. Anahtarlar Hubtel işletme panelinde bo.hubtel.com adresinde, Programmable keys altında bulunur.

IP beyaz listesi: Hubtel, Transaction Status API'sine yalnızca beyaz listeye alınmış sunucu IP adreslerinden yanıt verir. Hubtel'e (hesap yöneticinize veya support@hubtel.com adresine) web sunucunuzun genel IP adresini beyaz listeye eklemesini isteyin. O zamana kadar ödemeler onaylanamaz ve sipariş oluşturulmaz.

Test ortamı yok: Hubtel'in herkese açık bir sandbox ortamı yoktur. Tüm ödemeler gerçektir.

Cron: Arka plan ödeme kontrolleri için modülün cron URL'sini her 5 dakikada bir çağıran bir sunucu cron işi önerilir (bkz. Yapılandırma).

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

Kurulum

1. Back office'te Modules > Module Manager sayfasına 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 ya da daha sonra modül listesinde VibeFox Hubtel Pay Gateway öğ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ı girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

4. API ID, API Key ve satıcı hesap numarasını (POS Sales ID) girin.

5. Hubtel destek ekibinden sunucu IP adresinizi Transaction Status API için beyaz listeye eklemesini isteyin.

6. Configure sayfasında gösterilen cron URL'sini sunucunuzun cron ayarlarına ekleyin.

7. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Callback URL'si her ödemeyle birlikte Hubtel'e gönderildiği için Hubtel panelinde herhangi bir ayar yapmanız gerekmez.

Kurulumda modül Hubtel payment on hold sipariş durumunu oluşturur. PrestaShop, tüm para birimleri, ülkeler ve müşteri grupları için yeni bir ödeme modülü sunar. Bunları Payment > Preferences altından sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Hubtel Pay 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; API ID, API Key veya satıcı hesap numarası eksik olduğunda ve mağazanın varsayılan para birimi GHS değilse sizi uyarır. Her iki durumda da Hubtel ödeme sayfasında gizlenir. Ayrıca GHS para birimi 2'den fazla ondalık basamak kullanıyorsa uyarır.

Hubtel

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

Title: Müşterinin ödeme sayfasında gördüğü ödeme yöntemi adı. Siparişte de ödeme yönteminin adı olarak kaydedilir. Varsayılan: Mobile Money or card (Hubtel). Zorunlu: Boş bir başlık Enter a title for the payment method. hatasına yol açar.

Description: Ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Ödemeyi tamamlamak için Hubtel'e yönlendirileceksiniz.

Hubtel API kimlik bilgileri

API ID ve API Key değerlerini Hubtel işletme panelinden kopyalayın: bo.hubtel.com > Programmable keys. Satıcı hesap numarası, Hubtel hesabınızın POS Sales ID değeridir. Bu bölüm ayrıca IP beyaz listesi uyarısını da tekrarlar.

API ID (Client ID): Hubtel programlanabilir anahtarlarınızın API ID değeri.

API Key (Client Secret): Hubtel programlanabilir anahtarlarınızın API Key değeri. Gizli tutun. Kaydedilmiş anahtar bir daha asla 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.

Merchant account number (POS Sales ID): Ödemeler bu Hubtel hesabına tahsil edilir ve bu hesapla karşılaştırılır.

Clear saved API Key: Kutuyu işaretleyin ve kayıtlı API Key değerini kaldırmak için Save düğmesine tıklayın. Boş alan kayıtlı değeri korur.

Ödeme onayı

Callback URL: Callback, mağazanıza bir ödemenin yapıldığını bildirir. Bu URL her ödemeyle birlikte Hubtel'e gönderildiği için Hubtel panelinde herhangi bir ayar yapmanız gerekmez. SEO dostu URL'lerle şu biçimde görünür: https://your-shop/module/wcp_hubtel_pay/callback, başında bir dil kodu olabilir. İnternetten erişilebilir olmalıdır: Hubtel'i engelleyen parola koruması veya güvenlik duvarı olmamalıdır. Callback, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez.

Hubtel geri çağrıları imzalı değildir. Modül bir geri çağrıdan yalnızca ödeme referansını alır; bu referansın mağazanızdaki bir ödemeye ait olması gerekir. Durum, tutar ve işlem kimliği her zaman Hubtel Transaction Status API'sinden gelir. Sipariş, bu API ödemeyi ve tutarını onayladıktan sonra ödendi olarak oluşturulur.

Arka plan ödeme kontrolleri (cron): gizli bir token içeren cron URL'si. Sunucunuzun cron ayarlarından her 5 dakikada bir çağırın, örneğin curl ile. Onaylanmamış ödemeler bu şekilde Hubtel ile otomatik olarak yeniden kontrol edilir: müşteri Hubtel'e yönlendirildikten 20 dakika sonra, ödeme hâlâ ödenmemişse bir saat sonra bir kez daha ve Hubtel'e ulaşılamadığında artan aralıklarla en fazla 5 kez. URL'yi gizli tutun.

Gelişmiş

Debug log: API çağrılarını ve geri çağrıları modül klasöründeki logs/hubtel_p_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Anahtarlar ve müşteri verileri kaydedilmez. Hatalar ve uyarılar, bu seçenek kapalı olsa bile her zaman kaydedilir. Varsayılan: kapalı.

Log: Günlüğün mevcut boyutunu ve en son kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Delete data on uninstall: Açıksa modül kaldırıldığında bu modülün ayarları ve günlüğü silinir. Siparişler için kaydedilen Hubtel verileri ile Hubtel payment on hold sipariş durumu her zaman kalır. Varsayılan: kapalı.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Mobile Money or card (Hubtel)) ve onaylar. Modül, sepet toplamı için GHS cinsinden bir Hubtel ödeme sayfası oluşturur ve müşteriyi Hubtel ödeme sayfasına yönlendirir. Ödeme orada Cart #, sepet numarası ve mağazanızın adıyla görünür. Hubtel sayfasında müşteri MTN MoMo, Telecel Cash, AirtelTigo Money, Visa veya Mastercard kartı ya da GhQR ile öder. Bu aşamada henüz bir sipariş yoktur. Ödeme adımındaki her onay, kendi referansına sahip yeni bir ödeme girişimi oluşturur; aynı sepetin önceki Hubtel sayfaları da ödenebilir durumda kalır.

Ödemeyi yaptıktan sonra müşteri mağazanıza döner. Sipariş yalnızca Hubtel, Transaction Status API üzerinden onayladığında ödendi olarak işaretlenir: geri çağrı ile, müşterinin dönüşünde yapılan kontrolle, arka plan kontrolüyle veya sipariş sayfasındaki düğmeyle. Aynı anda gelen bir geri çağrı ve dönüş birbiri ardına işlenir; bu nedenle sipariş asla iki kez oluşturulmaz. Müşteri ardından standart sipariş onay sayfasını görür. Sipariş beklemeye alındıysa sayfa Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed. mesajını gösterir.

Müşteri döndüğünde Hubtel ödemeyi henüz onaylamadıysa, We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. mesajı ve Check again ile Back to checkout düğmelerini içeren bir Payment confirmation sayfası görünür. Hubtel ödemeyi onaylar onaylamaz sipariş oluşturulur. Hubtel bu ödeme girişimini zaten başarısız olarak bildirdiyse müşteri The Hubtel payment was not completed. You can try again or choose another payment method. mesajıyla ödeme sayfasına döner. Sepet korunur.

Müşteri Hubtel sayfasında Cancel düğmesine basarsa modül önce ödemenin yine de yapılıp yapılmadığını kontrol eder. Yapılmamışsa müşteri The Hubtel payment was cancelled. You can try again or choose another payment method. mesajıyla ödeme sayfasına döner. Sepet korunur. İptal edilen Hubtel sayfası üzerinden sonradan yapılan bir ödeme yine de kabul edilir.

Hubtel ödemeyi başlatamazsa müşteri ödeme sayfasında kısa bir mesajla kalır; örneğin Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. veya hatalı kimlik bilgileriyle Hubtel payments are not available at the moment. Please choose another payment method. Ayrıntılar günlüğe yazılır.

Modül, PrestaShop üzerinden para iadesini, abonelikleri, kayıtlı kartları ve mağaza içinde ödeme kanalı seçimini desteklemez.

Siparişler

Sipariş durumları

No order yet: Müşteri Hubtel'e yönlendirildi ve ödeme yapmadı ya da Hubtel ödemeyi henüz onaylamadı. Yalnızca sepet mevcuttur.

Payment accepted: Ödeme, GHS cinsinden sepet toplamının tam tutarı için onaylandı. Ödeme Hubtel işlem kimliğiyle kaydedilir ve bir not tutarı, Hubtel işlemini, ödeme yöntemini ve referansı gösterir.

Hubtel payment on hold: Hubtel, sepet toplamından farklı bir ödenen tutar bildirdi ya da sepet GHS cinsinden değil. Sipariş ödendi olarak işaretlenmedi; Hubtel'in gerçekten tahsil ettiği tutar bir ödeme olarak kaydedilir ve bir not uyuşmazlığı açıklar. Ödemeyi Hubtel panelinde kontrol edin, siparişi tamamlayın veya manuel olarak iade edin. Aynı sepetin başka bir girişimi sonradan doğru tutarla ödenirse sipariş Payment accepted durumuna geçer.

Zaten ödenmiş bir siparişin başka bir girişimi de ödenirse sipariş değişmez. Bir not, kopyayı Hubtel panelinizde iade etmenizi ister. İptal edilmiş veya iade edilmiş bir siparişe yapılan ödeme bir not ekler ve sipariş asla otomatik olarak yeniden açılmaz. Hubtel bir ödemeyi iade edilmiş olarak bildirdiğinde siparişe bir not eklenir.

Hubtel ödeme bloğu

Sipariş sayfasında, siparişin sepetine ait tüm ödeme girişimlerini gösteren bir Hubtel payment bloğu bulunur: tarih, referans, Hubtel ödeme sayfası, tutar, Hubtel durumu, işlem ve sonuç. Girişimlerin altında siparişin Hubtel notes notları, en yenisi önce olacak şekilde listelenir.

Check Hubtel payment status düğmesi, siparişin son girişimlerini denetler (en fazla 5, en yenisi önce; sipariş ödendiğinde durur), sonucu uygular ve her girişimin durumunu içeren bir not ekler. Sonuç blokta gösterilir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; Modules sayfalarına erişim gerekmez. Düğme, sipariş mevcut olduğunda kullanılabilir. Siparişi olmayan ödenmiş bir sepet, geri çağrı, müşterinin dönüşü veya cron ile onaylanır.

İadeler

PrestaShop üzerinden iade desteklenmez. Ödemeyi Hubtel panelinde iade edin, ardından iadeyi PrestaShop'ta kaydedin. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Hubtel üzerinden para geri göndermez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox Hubtel Pay Gateway, Modules > Module Manager > VibeFox Hubtel Pay Gateway > 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ı 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-hubtel 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 gösterir; ö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 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 Hubtel, ö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ü 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 arka plan ödeme kontrolleriyle de onaylanmaya devam eder.

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, sonra haftada bir kez. Lisans kontrolü için cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

Hubtel ödeme sayfasında görünmüyor: Lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu, API ID, API Key ve satıcı hesap numarasının doldurulduğunu ve sepet para biriminin GHS olduğunu kontrol edin. Payment > Preferences altında modülün GHS, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu doğrulayın. Kimlik bilgileri veya para birimi hatalıysa ayarlar sayfası bir uyarı gösterir.

Ödeme yapıldı ama sipariş oluşturulmadı: Ödeme onaylanamadı. Debug log seçeneğini açın ve modül sayfasındaki Log alanına bakın. Durum kontrolünde HTTP 401 veya 403, API anahtarlarının hatalı olduğu ya da sunucu IP adresinin Hubtel tarafından beyaz listeye alınmadığı anlamına gelir. Ayrıca callback URL'sinin internetten erişilebilir olduğunu ve cron URL'sinin çağrıldığını kontrol edin. Hubtel yanıt verdiği anda bir sonraki geri çağrı, arka plan kontrolü veya müşterinin dönüşü siparişi oluşturur.

Callback Unknown reference yanıtı veriyor: Ödeme referansı bu mağazanın bir ödemesine ait değil.

Callback Payment status unavailable yanıtı veriyor: Transaction Status API'sine ulaşılamadı ya da isteği reddetti veya sepet aynı anda başka bir istek tarafından onaylanıyordu. Ödeme 5 dakika sonra arka planda yeniden kontrol edilir.

Callback Gateway not configured yanıtı veriyor: API ID, API Key veya satıcı hesap numarası eksik. Bunları doldurun; ödeme arka planda yeniden kontrol edilir.

Callback Invalid request veya Invalid ClientReference yanıtı veriyor: İstek geçerli bir Hubtel geri çağrısı içermiyordu.

Callback URL'si tarayıcıda Method not allowed gösteriyor: Bu normaldir. URL yalnızca Hubtel'den gelen istekleri kabul eder.

Cron URL'si Forbidden yanıtı veriyor: URL'deki token yanlış. Cron URL'sini ayarlarda gösterildiği gibi birebir kopyalayın.

Sipariş Hubtel payment on hold durumunda: Hubtel payment bloğundaki notları okuyun (bkz. Sipariş durumları), ödemeyi Hubtel panelinde kontrol edin ve siparişi tamamlayın ya da manuel olarak iade edin.

Müşteri Hubtel'i seçerken hata görüyor: Debug log seçeneğini açın ve günlüğe bakın. Hatalı API anahtarları Hubtel payments are not available at the moment. hatasını verir. Bağlantı sorunu Could not connect to Hubtel. hatasını verir. Başka bir para birimindeki sepet Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method. hatasını verir.

Geliştiriciler için: actionWcpHubtelPayIcon kancası ödeme yöntemi simgesini değiştirir, actionWcpHubtelPayPaymentDescription kancası ise Hubtel sayfasındaki ödeme açıklamasını değiştirir (en fazla 100 karakter).

Kaldırma

Modules > Module Manager sayfasına gidin, VibeFox Hubtel Pay Gateway satırının 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 bu modülün ayarları ve günlüğü silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Siparişler için kaydedilen Hubtel verileri ve Hubtel payment on hold sipariş durumu her zaman saklanır. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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