VibeFox PayMongo for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

PHP: 8.0 veya üzeri. Modül, daha eski PHP sürümlerine kurulmayı reddeder.

Para birimi: Filipin pezosu (PHP). PayMongo, ödeme sayfasında yalnızca PHP cinsindeki sepetler için gösterilir. Mağazanızın varsayılan para birimi PHP değilse ayarlar sayfası sizi uyarır ve PayMongo'yu görmek için müşterilerin PHP'ye geçmesi gerekir.

PayMongo hesabı: PayMongo hesabınızın API gizli anahtarlarına ve her mod için bir webhook'a ihtiyacınız vardır (bkz. Yapılandırma). Yalnızca gizli anahtarlar (sk_test_..., sk_live_...) ve webhook imza gizli anahtarları (whsk_...) kullanılır. Ödeme sayfası PayMongo tarafından barındırıldığı için genel anahtarlara gerek yoktur. Sunduğunuz ödeme yöntemleri PayMongo hesabınızda etkinleştirilmiş olmalıdır.

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

Kurulum

1. Yönetim panelinde 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 bittiğinde Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox PayMongo Payment 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. PayMongo gizli anahtarlarınızı yapıştırın, PayMongo'da webhook'ları oluşturun ve imza gizli anahtarlarını yapıştırın (bkz. Yapılandırma).

5. Ödeme yöntemlerini seçin, Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test mode açıkken bir ödeme deneyin, ardından kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting PayMongo payment ve PayMongo payment on hold. Payment > Preferences bölümünde modülün Filipin pezosu, müşterilerinizin ülkeleri ve müşteri grupları için izinli olduğunu kontrol edin.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox PayMongo 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; mağazanın varsayılan para birimi PHP değilse, geçerli modda gizli anahtar yoksa (PayMongo bu durumda ödeme sayfasında gösterilmez) veya webhook gizli anahtarı yoksa (bu durumda ödemeler yalnızca müşteri mağazanıza döndüğünde onaylanır) sizi uyarır. Test modu açıkken de Test mode is on: no real payments are made. ifadesini gösterir.

PayMongo

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

Title: müşterinin ödeme sayfasında gördüğü ödeme yönteminin adı. Siparişte de bu ad kaydedilir. Varsayılan: PayMongo (Card, GCash, GrabPay, Maya). Zorunlu.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: PayMongo ödeme sayfasında sunulan yöntemler. Yalnızca PayMongo hesabınızda etkinleştirilmiş yöntemleri seçin; aksi halde PayMongo ödemeyi reddeder. Hiçbiri seçilmezse varsayılanlar kullanılır. Varsayılan: Cards, GCash, GrabPay and Maya.

API anahtarları

Gizli anahtarları PayMongo Dashboard > Developers > API keys bölümünden kopyalayın. Genel anahtarlara gerek yoktur. Her anahtar beklenen önekle başlamalıdır. Yanlış önekli bir değer kaydedilmez: sayfa, must start with alanının öneki içermesi gerektiğini ve The previous value was kept. ifadesini gösterir.

Test mode: Enable test mode (no real payments). Yeni ödemeler test anahtarlarını kullanır. Daha önce yapılan ödemeler, yapıldıkları modu korur; bu nedenle durum kontrolleri ve iadeler ilgili anahtarı kullanır. Varsayılan: açık. Gerçek ödeme almak için kapatın.

Test secret key: test modunun gizli anahtarı. sk_test_ ile başlar.

Test webhook secret: test modu webhook'unun imza gizli anahtarı. whsk_ ile başlar.

Live secret key: canlı modun gizli anahtarı. sk_live_ ile başlar.

Live webhook secret: canlı mod webhook'unun imza gizli anahtarı. whsk_ ile başlar.

Kaydedilmiş anahtarlar ve gizli anahtarlar 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.

Clear saved secrets: bir anahtarın veya gizli anahtarın kutusunu işaretleyip Save düğmesine tıklayarak kaldırın. Boş alan kayıtlı değeri korur.

Webhook

Webhook, müşteri ödemeden sonra tarayıcıyı kapatsa bile mağazanıza bir ödemenin yapıldığını bildirir. Test ve canlı modların her biri için PayMongo Dashboard'da (veya PayMongo API'si üzerinden) bu bölümdeki Webhook URL alanında gösterilen URL ile bir webhook oluşturun. Dostane URL'ler etkinken şuna benzer: https://your-shop/module/wcp_paymongo_payment_gateway/webhook; sonunda /en/ gibi bir dil kodu da olabilir. URL'yi ayarların gösterdiği gibi birebir kopyalayın.

Şu olayları seçin (bu bölümde de listelenmiştir):

Her webhook'un imza gizli anahtarını (whsk_...) Test webhook secret veya Live webhook secret alanına kopyalayın. Geçerli imzası olmayan webhook'lar reddedilir. İmza, kendi modunun gizli anahtarıyla kontrol edilir ve olayın modu bununla eşleşmelidir; bu nedenle test webhook'u hiçbir zaman canlı bir ödemeyi onaylamaz. Her olay, bir sipariş oluşturulmadan veya değiştirilmeden önce ödemenin modundaki gizli anahtarla PayMongo API'si üzerinden yeniden kontrol edilir. PayMongo, hesabın tüm olaylarını her webhook'a gönderir; bu mağazada başlatılmamış ödemelerin olayları yok sayılır. Webhook olmadan sipariş, yalnızca müşteri ödemeden sonra mağazaya döndüğünde oluşturulur.

Siparişler

Order status after payment: başarılı bir ödemeden sonra ayarlanan sipariş durumu.

Hâlâ işlenmekte olan ödemeler Awaiting PayMongo payment durumunda bekler. Tutar veya para birimi uyuşmazlıkları ile canlı bir mağazadaki test ödemeleri her zaman PayMongo payment on hold durumuna gider.

Gelişmiş

Debug log: PayMongo API çağrılarını ve webhook olaylarını modül klasöründeki logs/paymongo_p_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar, anahtar kapalıyken bile her zaman kaydedilir. Anahtarlar ve müşteri verileri hiçbir zaman kaydedilmez. 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ırmak ayarları ve günlüğü siler. Siparişler için saklanan PayMongo kimlikleri, iadeler ve modülün sipariş durumları her zaman korunur, çünkü iadeler ve muhasebe için gerekirler. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak PayMongo (Card, GCash, GrabPay, Maya)) ve açıklamasını görür. Test modunda ödeme sayfasında ayrıca Test mode: no real payment will be made. ifadesi gösterilir. PayMongo yalnızca toplamı en az ₱100,00 olan PHP sepetler için sunulur.

Onaylandıktan sonra modül, sepet toplamı için PHP cinsinden bir PayMongo Checkout Session oluşturur; bir satırda Cart # ve sepet numarasını ekler ve müşteriyi PayMongo ödeme sayfasına yönlendirir. Müşterinin adı, e-postası, telefonu ve fatura adresi PayMongo'ya iletilir. Orada müşteri seçilen yöntemlerden birini seçer ve öder. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca PayMongo ödemeyi onayladıktan sonra ödenmiş olarak işaretlenir: Modül, müşteri döndüğünde ve webhook geldiğinde PayMongo API'sine ödemeyi sorar. Ardından sipariş oluşturulur ve müşteri Your PayMongo payment has been received. ifadesini içeren standart sipariş onay sayfasını görür. Müşteri döndüğünde PayMongo hâlâ ödemeyi işliyorsa sipariş Awaiting PayMongo payment durumunda oluşturulur ve sayfa PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. ifadesini gösterir. Bu ödeme daha sonra başarısız olursa sayfa Your PayMongo payment was not completed. Please contact us about this order. ifadesini gösterir. Müşteri döndüğünde PayMongo'ya ulaşılamazsa, müşteriden tekrar ödeme yapmamasını isteyen bir Payment confirmation sayfası ve bir Check again düğmesi görüntülenir; webhook geldiği anda siparişi oluşturur.

Müşteri PayMongo sayfasında iptal ederse veya ödemeyi tamamlamazsa, ödeme adımına You cancelled the PayMongo payment. You can try again or choose another payment method. veya Your PayMongo payment was not completed. You can try again or choose another payment method. mesajıyla döner. Sepet korunur. Yeni bir deneme önce öncekini kontrol eder: Bu arada ödenmişse sipariş yeni bir ödeme olmadan oluşturulur; aksi halde önceki PayMongo ödeme bağlantısı geçersiz hale gelir, böylece sepet iki kez ödenemez. Önceki ödeme hâlâ işlenirken müşteri Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again. mesajını görür.

PayMongo ödemeyi başlatamazsa müşteri ödeme adımında kısa bir mesajla kalır; örneğin The payment could not be started. Please try again or choose another payment method. veya PayMongo could not be reached. Please try again in a moment. Teknik neden günlüğe yazılır.

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

Modül, PayMongo sayfasında tek seferlik ödemeleri kabul eder. Kendi ödeme sayfanızda kart alanı, kayıtlı kart, abonelik veya yinelenen ödeme, taksit ve ayrı yetkilendirme/tahsilat yoktur.

Siparişler ve iadeler

Sipariş durumları

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

Payment accepted or Delivered: Ödeme onaylandı. Durum, Order status after payment ayarını izler. Ödeme, işlem kimliği olarak PayMongo ödeme kimliğiyle (pay_...) kaydedilir; bir not ödemeyi, tutarı, yöntemi, modu ve onayın nasıl yapıldığını (webhook veya dönüş) gösterir.

Awaiting PayMongo payment: Müşteri, PayMongo ödemeyi hâlâ işlerken döndü. Sipariş, PayMongo onayladığında ödenmiş durumuna geçer.

PayMongo payment on hold: Ödenen tutar veya para birimi sepet toplamından farklıdır (örneğin ödeme başladıktan sonra sepet başka bir sekmede değiştirildi); ya da mağaza canlı moddayken bir test modunda ödeme yapıldı, bu nedenle hiçbir para alınmadı ve ödeme kaydedilmedi; ya da ödeme, sipariş iptal edildikten sonra geldi. Not bunu açıklar. Siparişi kontrol edip işleyin veya ödemeyi iade edin.

Payment error: İmzalı bir payment.failed webhook'u, Awaiting PayMongo payment durumundaki bir siparişin son ödeme denemesinin başarısız olduğunu bildirdi. Not, PayMongo hata kodunu ve mesajını gösterir. Aynı ödeme daha sonra başarılı olursa sipariş ödenmiş durumuna geçer.

Refunded: Ödeme, modül aracılığıyla tamamen iade edildi.

Zaten ödenmiş bir sipariş için ikinci bir ödeme gelirse (örneğin eski bir ödeme bağlantısı üzerinden), sipariş değişmez. Bir not, mükerrer ödemeyi PayMongo Dashboard'da iade etmenizi ister. Ödenmiş ve sonra iptal edilen veya iade edilen bir sipariş asla yeniden açılmaz.

PayMongo payment bloğu

Sipariş sayfasında; PayMongo ödeme kimliği ve yöntemi, payment intent, checkout, mod, durum, ödenen tutar ve iade edilen tutar, test ödemeleri için bir Test mode rozeti, siparişin PayMongo notları ve iade geçmişi içeren bir PayMongo payment bloğu gösterilir.

İadeler

PayMongo payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isterseniz bir neden yazın ve Refund via PayMongo düğmesine tıklayın. Refund this amount through PayMongo? This cannot be undone. sorusunu onaylayın. En fazla iki ondalık basamakla tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine ihtiyacınız vardır; modül sayfalarına erişim gerekmez. İadeler, PayMongo'nun gerçekten tahsil ettiği tutarla sınırlıdır; bu nedenle tutar uyuşmazlığından sonra sipariş toplamına değil, müşterinin ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı modun (test veya canlı) gizli anahtarıyla gönderilir; bu nedenle o modun anahtarı ayarlanmış olmalıdır. Girdiğiniz neden, PayMongo'ya iade notu olarak gönderilir. PayMongo iadeyi kabul etmezse blok hatayı gösterir ve iade kaydedilmez. Başarılı bir iade, PayMongo iade kimliği ve durumuyla birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez.

Modül, mahsup belgesi oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri, PayMongo üzerinden para geri göndermez. PayMongo Dashboard'da yapılan iadeler PrestaShop'a aktarılmaz. Bunun yerine sipariş bloğundan iade yapın veya siparişi elle güncelleyin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınmış bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox PayMongo Payment Gateway, Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure sayfasının en üstündeki ilk bloktur ve ayarların üstündedir. 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 tarihi ve alan adınızı) ve Check now (durumu yeniden kontrol eder), Change key (başka bir anahtar girer) ve Remove key (anahtarı bu mağazadan kaldırır) düğmelerini gösterir. Bunların altında Product: presta-payment-paymongo satırı ile Manage licenses and domains in your account bağlantısı bulunur; bu bağlantı vibefox.net hesabınızı açar. 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 License expired on ve bir tarih. Mağaza adresi değiştikten sonra ya da hesabınızda bir alan adı yuvasını boşalttı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ı boşaltmaz. Yuvayı vibefox.net hesabınızdan boşaltın.

Etkin bir anahtar olmadan PayMongo, ö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 sayfasında Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır 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, sonrasında haftada bir. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

PayMongo ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu, geçerli modda bir gizli anahtar bulunduğunu (test modunda Test secret key, canlı modda Live secret key), sepetin PHP cinsinden olduğunu ve toplamın en az ₱100,00 olduğunu kontrol edin. 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 başarılı oldu ama sipariş oluşturulmadı: Webhook çalışmıyor ve müşteri mağazaya dönmedi. PayMongo Dashboard'da kullandığınız modda bir webhook olduğunu, URL'sinin Webhook URL alanında gösterilenle tamamen aynı olduğunu ve üç olayın da seçili olduğunu kontrol edin. İmza gizli anahtarının ilgili alanda (Test webhook secret veya Live webhook secret) olduğunu kontrol edin.

Webhook Invalid signature yanıtı veriyor: Bu modun imza gizli anahtarı eksik veya başka bir webhook'a ait. Webhook'un imza gizli anahtarını kendi modunun alanına yapıştırın.

Webhook Mode mismatch yanıtı veriyor: Bir test olayı canlı olarak imzalanmış ya da tersi. Her webhook'un doğru moda ait olduğunu kontrol edin.

Webhook Temporary error yanıtı veriyor: Ödeme PayMongo API'si üzerinden kontrol edilemedi; örneğin ödemenin modunun gizli anahtarı eksik. PayMongo webhook'u otomatik olarak yeniden dener.

Webhook Busy, retry yanıtı veriyor: Sipariş aynı anda başka bir istek tarafından onaylanıyordu veya sipariş oluşturulamadı (örneğin modül devre dışı). PayMongo webhook'u otomatik olarak yeniden dener. Nedeni Log içindedir.

Webhook Ignored yanıtı veriyor: Olay, bu mağazada başlatılmamış bir ödemeye veya başka bir moda ait. Hiçbir şey değişmez.

Webhook URL'si tarayıcıda Method not allowed gösteriyor: Bu normaldir. URL yalnızca PayMongo'dan gelen istekleri kabul eder.

Değer kaydedilmedi: Bir anahtar yanlış alana yapıştırılmış. Gizli anahtarlar sk_test_ veya sk_live_ ile, webhook gizli anahtarları whsk_ ile başlar.

Müşteri PayMongo'yu seçerken hata görüyor: Modül sayfasındaki Log alanına bakın. Yanlış bir gizli anahtar, ödeme yönteminin geçici olarak kullanılamadığı mesajına yol açar. PayMongo hesabınızda etkinleştirilmemiş bir ödeme yöntemi PayMongo'nun ödemeyi reddetmesine neden olur; bunu Payment methods bölümünden kaldırın.

Canlı bir mağazada test ödemeleri: Mağaza canlı moddayken gelen bir test ödemesi, siparişi PayMongo payment on hold durumuna alır ve hiçbir paranın alınmadığını belirten bir not ekler. Gerçek ödemeler, test moduna geri dönülse bile her zaman tanınır ve canlı anahtarla iade edilir.

Ödemeden sonra sipariş PayMongo payment on hold durumunda: PayMongo payment bloğundaki notları okuyun (bkz. Sipariş durumları), ardından siparişi işleyin veya ödemeyi iade edin.

İade, mod ile ilgili bir mesajla başarısız oluyor: Ödeme test veya canlı modda yapılmış ve o modun gizli anahtarı ayarlanmamış. Anahtarı girin ve tekrar deneyin.

Geliştiriciler, Checkout Session verilerini actionPaymongoPCheckoutSessionData kancasıyla değiştirebilir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox PayMongo 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 ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Siparişlerin PayMongo kimlikleri, iadeler ve Awaiting PayMongo payment ile PayMongo payment on hold sipariş durumları her zaman korunur; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler, ödeme notlarını ve işlem kimliklerini korur.

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