VibeFox Hubtel for WooCommerce — Yardım

Gereksinimler

WordPress: 6.2 veya üzeri.

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

PHP: 8.0 veya üzeri.

Para birimi: Yalnızca Gana cedisi (GHS). Ödeme yöntemi diğer para birimleri için ödeme sayfasında gizlenir. Hubtel tam pesewa cinsinden tahsilat yaptığından, WooCommerce ondalık basamak sayısını 2'de tutun.

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

IP beyaz listesi: Hubtel, Transaction Status API sorgularına yalnızca beyaz listeye alınmış sunucu IP adreslerinden yanıt verir. Web sunucunuzun genel IP adresini beyaz listeye almasını Hubtel'den (hesap yöneticinizden veya support@hubtel.com adresinden) isteyin. Bu yapılana kadar ödemeler onaylanamaz ve siparişler Ödeme bekleniyor durumunda kalır.

Test ortamı yoktur: Hubtel'in genel bir sandbox ortamı yoktur. Tüm ödemeler gerçektir.

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 bölümüne gidin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_hubtel_pay 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 > Hubtel > Manage yolunu izleyin veya Eklentiler sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

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

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

6. Transaction Status API için sunucu IP'nizi beyaz listeye almasını Hubtel destek ekibinden talep edin.

7. Enable/Disable seçeneğini açın. Callback URL'si her ödemeyle birlikte Hubtel'e gönderildiğinden Hubtel panelinde herhangi bir ayar yapılması gerekmez.

Yapılandırma

Tüm ayarlar tek bir sayfadadır: WooCommerce > Settings > Payments > Hubtel. Alanların üzerinde sayfa; API ID, API Key veya satıcı hesap numarası eksik olduğunda ve mağaza para birimi GHS olmadığında sizi uyarır. Her iki durumda da Hubtel ödeme sayfasında gizlenir. Ayrıca mağaza 2'den fazla ondalık basamak kullandığında da sizi uyarır. Ödeme yöntemleri listesinde kimlik bilgileri doldurulana kadar ağ geçidi kurulum gerektiriyor olarak işaretlenir.

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ı. Varsayılan: Mobile Money or card (Hubtel).

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. You will be redirected to Hubtel to complete the payment.

Hubtel API kimlik bilgileri

API ID ve API Key değerlerini Hubtel işletme panelinizden 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 bildirimini de yineler.

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.

Merchant account number (POS Sales ID): Ödemeler bu Hubtel hesabında toplanır ve bu hesaba göre denetlenir.

Ödeme onayı

Geri çağrı (callback), mağazanıza bir ödemenin yapıldığını bildirir. Bu bölümde gösterilen callback URL'si her ödemeyle birlikte Hubtel'e gönderilir, bu nedenle Hubtel panelinde hiçbir şey yapılandırmanız gerekmez. https://your-site/wc-api/hubtel_pay/ benzeri bir görünümdedir. İnternetten erişilebilir olmalıdır: bakım modu, parola koruması veya Hubtel'i engelleyen bir güvenlik duvarı bulunmamalıdır.

Hubtel geri çağrıları imzalı değildir. Eklenti bir geri çağrıdan yalnızca ödeme referansını alır; bu referans mağazanızın bir siparişine ait olmalıdır. Durum, tutar ve işlem kimliği her zaman Hubtel Transaction Status API'sinden gelir. Sipariş, ancak bu API ödemeyi ve tutarını onayladıktan sonra ödendi olarak işaretlenir. Hubtel'e ulaşılamazsa ödeme arka planda otomatik olarak yeniden kontrol edilir ve bunu sipariş ekranından Order actions > Check Hubtel payment status ile de denetleyebilirsiniz.

Gelişmiş

Debug log: WooCommerce > Status > Logs konumuna anahtarlar veya müşteri verileri olmadan Log API calls and callbacks kaydı tutar, kaynak wcp_hubtel_pay. Hatalar her zaman günlüğe kaydedilir. Varsayılan: kapalı.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Varsayılan: kapalı.

Ödeme süreci

Müşteri ödeme yöntemini seçer (varsayılan olarak Mobile Money or card (Hubtel)) ve siparişi verir. Eklenti, GHS cinsinden sipariş toplamı için bir Hubtel ödemesi oluşturur ve müşteriyi Hubtel ödeme sayfasına gönderir. Ödeme orada Order #, sipariş numarası ve sitenizin adı olarak görünür. Hubtel sayfasında müşteri MTN MoMo, Telecel Cash, AirtelTigo Money, Visa veya Mastercard kartı ya da GhQR ile ödeme yapar. Place order veya Pay düğmesine her tıklama kendi referansına sahip yeni bir ödeme denemesi oluşturur ve aynı siparişin daha eski Hubtel sayfaları ödenebilir durumda kalır.

Ödemeden sonra müşteri sipariş alındı sayfasına döner. Sipariş, ancak Hubtel bunu Transaction Status API aracılığıyla onayladıktan sonra ödendi olarak işaretlenir: geri çağrı ile, müşteri geri döndüğünde yapılan kontrol ile, bir arka plan kontrolü ile veya sipariş işlemi ile. Aynı anda gelen bir geri çağrı ve bir geri dönüş art arda işlenir, böylece sipariş asla iki kez tamamlanmaz. Hubtel ödemeyi henüz onaylamadıysa sayfada şu mesaj görünür: 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. Sipariş beklemede durumuna alındıysa şu mesaj görünür: Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Müşteri Hubtel sayfasında Cancel düğmesine basarsa, eklenti önce ödemenin yine de yapılıp yapılmadığını kontrol eder. Yapılmadıysa müşteri The Hubtel payment was cancelled. You can try again or choose another payment method. mesajı ile Pay for order sayfasına geri döner.

Hubtel ödemeyi başlatamazsa müşteri kısa bir mesaj görü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 yanlış kimlik bilgileriyle Hubtel payments are not available at the moment. Please choose another payment method. Ayrıntılar günlüğe kaydedilir.

Ödeme yöntemi klasik ödeme sayfasında, Ödeme bloğunda ve Pay for order sayfasında çalışır. WooCommerce Yüksek Performanslı Sipariş Depolama (HPOS) ile uyumludur.

Eklenti WooCommerce üzerinden para iadesini, abonelikleri, kayıtlı kartları ve WooCommerce içinde ödeme kanalı seçimini desteklemez.

Siparişler

Sipariş durumları

Pending payment: Müşteri Hubtel'e gönderildi ve henüz ödeme yapmadı ya da Hubtel ödemeyi henüz onaylamadı.

Processing: Ödeme onaylandı. Yalnızca sanal indirilebilir ürünler içeren siparişler WooCommerce varsayılanı olan Tamamlandı durumuna geçer. Sipariş notu tutarı, Hubtel işlemini, ödeme yöntemini ve referansı gösterir. İşlem kimliği Hubtel işlem kimliğidir.

On hold: Hubtel sipariş toplamından farklı bir ödenen tutar bildirdi veya sipariş GHS cinsinden değil (not: Hubtel amount/currency mismatch); ya da daha önce iptal edilmiş bir sipariş için ödeme geldi. Sipariş ödendi olarak işaretlenmedi. Ödemeyi Hubtel panelinde kontrol edin ve siparişi manuel olarak tamamlayın veya iade edin.

Failed: Hubtel, bekleyen bir siparişin son ödeme denemesinin başarısız olduğunu bildirdi ve Transaction Status API siparişin ödenmediğini onaylıyor. Müşteri sipariş üzerinden tekrar deneyebilir. Yalnızca geri çağrı ile bildirilen bir başarısızlık siparişi asla başarısız duruma düşürmez.

Zaten ödenmiş bir siparişin başka bir denemesi de ödenirse sipariş değiştirilmez. Bir not, Hubtel panelinizde mükerrer ödemeyi iade etmenizi ister. İptal edilmiş veya iade edilmiş bir sipariş asla otomatik olarak yeniden açılmaz. Hubtel bir ödemeyi iade edilmiş olarak bildirdiğinde siparişe bir not eklenir.

Ödeme kontrolleri

Müşteri Hubtel'e gönderildikten yaklaşık 20 dakika sonra, geri çağrının kaybolması ve müşterinin geri dönmemesi ihtimaline karşı bir arka plan kontrolü (WooCommerce Action Scheduler) Hubtel'e ödemeyi sorar. Ödenmemiş bir deneme bir saat sonra bir kez daha denetlenir. Hubtel API'sine ulaşılamadığında denetim, artan aralıklarla 5 defaya kadar yinelenir.

Check Hubtel payment status sipariş işlemi, siparişin en son denemelerini denetler (en yeniden başlayarak 5 taneye kadar), sonucu uygular ve her denemenin durumunu belirten bir not ekler.

İadeler

WooCommerce üzerinden para iadeleri desteklenmez. Ödemeyi Hubtel panelinde iade edin, ardından WooCommerce'te manuel bir iade oluşturun.

Lisans anahtarı

Eklenti vibefox.net üzerinden alınan bir VibeFox lisans anahtarı ile çalışır. Lisans bloğu WooCommerce > Settings > Payments > Hubtel sayfasının üst kısmındadır. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blok; durumu, örneğin lisansın hangi tarihe kadar etkin olduğunu ve alan adınızı gösterir. Durumu yeniden denetlemek için Check now, başka bir anahtar girmek için Change key ve bu siteden kaldırmak için Remove key düğmesini 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ın bir siteden kaldırılması alan adı hakkını serbest bırakmaz. Alan adı hakkını vibefox.net hesabınızda 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 şunu görür: This payment method is not available. Please choose another one. Oturum açmış mağaza yöneticileri ödeme yöntemini (unlicensed — visible to admins only) olarak işaretli şekilde 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ırlatıcı görünür. Mevcut siparişler etkilenmez: Başlatılmış ödemeler onaylanmaya devam eder.

Bir 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

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 para biriminin GHS olduğunu kontrol edin. Pay for order sayfasında siparişin para birimi geçerlidir. Kimlik bilgileri veya para birimi yanlış olduğunda ayarlar sayfası bir uyarı görüntüler.

Ödeme gerçekleşti ancak sipariş Ödeme bekleniyor durumunda kalıyor: Ödeme onaylanamadı. WooCommerce > Status > Logs konumunu açın, kaynak wcp_hubtel_pay. Durum denetiminde HTTP 401 veya 403 hatası, API anahtarlarının yanlış olduğu veya sunucu IP'sinin Hubtel tarafından beyaz listeye alınmadığı anlamına gelir. Ayrıca callback URL'sinin internetten erişilebilir olduğunu kontrol edin. Sorunu giderdikten sonra siparişi açın ve Order actions > Check Hubtel payment status işlemini yürütün. Arka plan kontrolleri de Hubtel yanıt verdiğinde siparişi onaylar.

Geri çağrı Unknown reference yanıtı veriyor: Ödeme referansı bu mağazanın bir siparişine ait değildir.

Geri çağrı Payment status unavailable yanıtı veriyor: Transaction Status API'sine ulaşılamadı veya istek reddedildi. Ödeme arka planda yeniden denetlenir.

Sipariş, tutar/para birimi uyuşmazlığı notuyla Beklemede durumunda: Hubtel sipariş toplamından farklı bir ödenen tutar bildirdi veya sipariş GHS cinsinden değil. Ödemeyi Hubtel panelinde kontrol edin ve siparişi manuel olarak tamamlayın veya iade edin.

Müşteri sipariş verirken bir hata görüyor: Debug log seçeneğini açın ve günlüğü inceleyin. Yanlış API anahtarları Hubtel payments are not available at the moment. hatasını verir. Bağlantı sorunu ise Could not connect to Hubtel. hatasını verir.

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 alan adı hakkını serbest bırakın ve Check now düğmesine tıklayın. Site adresi değiştiyse anahtarı yeni alan adı için etkinleştirmek üzere Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamıyorsa eklenti bilinen son durumla çalışmaya devam eder.

Geliştiriciler için: hubtel_p_icon filtresi ödeme yöntemi simgesini, hubtel_p_payment_description filtresi ise Hubtel sayfasındaki ödeme açıklamasını değiştirir (100 karaktere kadar).

Kaldırma

Eklenti devre dışı bırakıldığında tüm veriler korunur; yalnızca bekleyen arka plan ödeme denetimleri iptal edilir. Kaldırmak için Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ağ geçidi ayarları, eklentinin kendi seçenekleri, bekleyen arka plan kontrolleri ve günlükler yalnızca Delete data on uninstall açıksa kaldırılır. Aksi halde daha sonra yeniden kurulum için korunurlar. Siparişlerde saklanan Hubtel verileri ödeme geçmişidir ve her zaman korunur. Mevcut siparişler ödeme notlarını ve işlem kimliklerini saklar.

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