VibeFox Peach Payments for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x.

PHP: OpenSSL uzantılı 8.0 veya üzeri (webhook'ların şifresini çözmek için kullanılır). Bunlar olmadan modül kurulmaz.

Para birimi: sepetin para birimi ZAR, KES veya MUR olmalıdır. Diğer para birimlerindeki sepetler için ödeme yöntemi gizlenir. Ayarlar sayfası, mağazanın varsayılan para biriminin bunlardan biri olmadığını görürse sizi uyarır.

Peach Payments hesabı: Peach Payments hesabınızın Card API kimlik bilgilerine ihtiyacınız var: Entity ID ve Access Token. Test bilgileri Peach Payments sandbox panelinden, canlı bilgiler Peach Payments panelinden alınır; ikisi farklıdır. Webhook'lar için ayrıca, mağazanız için Card webhook'larını etkinleştirdiğinde Peach Payments'ın gönderdiği webhook şifre çözme anahtarına da ihtiyacınız vardır (bkz. Yapılandırma). Webhook alabilmek için mağazanızın internetten erişilebilir olması gerekir.

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 Peach Payments 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. Peach Payments sandbox panelinden test Entity ID ve Access Token bilgilerini girin ve ayarlar sayfasında gösterilen webhook URL'si için Peach Payments'tan Card webhook'larını etkinleştirmesini isteyin (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test mode açık kalsın ve bir Peach Payments sandbox test kartıyla ödeme yapın. Ardından Test mode seçeneğini kapatın, canlı bilgileri ve canlı webhook anahtarını girin ve Save düğmesine tıklayın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Peach Payments payment ve Peach Payments payment on hold. PrestaShop, o anda etkin olan para birimleri, ülkeler ve müşteri grupları için yeni bir ödeme modülü sunar. Sonradan eklenen ülkeler, Payment > Preferences bölümünde modül için etkinleştirilmelidir; bu bölümde ülkeleri sınırlandırabilirsiniz de.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Her bölümün kendi Save düğmesi vardır ve tüm sayfayı kaydeder. Alanların üstünde sayfa şu bildirimleri gösterir: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; geçerli modun Entity ID'si veya Access Token'ı eksikse bir hata (o zamana kadar ödeme yöntemi ödeme adımında gösterilmez); geçerli modun webhook şifre çözme anahtarı eksikse bir uyarı (bu durumda ödemeler yalnızca müşteri mağazaya döndüğünde onaylanır); ve mağazanın varsayılan para birimi desteklenmiyorsa bir hata. Kaydederken kimlik bilgilerindeki boşluklar silinir ve 64 karakterlik onaltılık bir değer olmayan webhook anahtarı uyarıyla bildirilir.

Peach Payments

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

Title: ödeme adımında müşteriye gösterilen ödeme yönteminin adı. Siparişte de ödeme yönteminin adı olarak kaydedilir. Varsayılan: Credit / Debit Card (Peach Payments). Zorunlu.

Description: ödeme adımında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API credentials

Card API'nin Access Token ve Entity ID bilgileri Peach Payments panelinde gösterilir (test bilgileri sandbox panelinde). Bölüm, her iki panele ve Peach Payments geliştirici belgelerine bağlantılar içerir.

Test mode: yeni ödemeleri test bilgileriyle Peach Payments sandbox ortamına gönderir; gerçek para çekilmez. Gerçek ödemeleri canlı bilgilerle kabul etmek için kapatın. Bir modda başlatılan ödeme, mod değiştirilse bile her zaman o modda kontrol edilir. Varsayılan: açık.

Test Entity ID: sandbox hesabınızın Entity ID'si (3-D Secure kanalı).

Test Access Token: sandbox hesabınızın bearer erişim belirteci.

Test Webhook Decryption Key: sandbox Card webhook'larının şifresini çözmek için kullanılan 64 karakterlik onaltılık anahtar.

Live Entity ID: canlı hesabınızın Entity ID'si (3-D Secure kanalı).

Live Access Token: canlı hesabınızın bearer erişim belirteci.

Live Webhook Decryption Key: canlı hesabınızın Card webhook'larının şifresini çözmek için kullanılan 64 karakterlik onaltılık anahtar.

Kaydedilmiş erişim belirteçleri ve webhook anahtarları bir daha 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 erişim belirtecini veya webhook anahtarını işaretleyip Save düğmesine tıklayarak kaldırın. Boş alan, kaydedilmiş değeri korur.

Webhook

Webhook'lar, müşteri mağazaya dönmeden tarayıcıyı kapatsa bile ödemeleri onaylar. Webhook URL alanı mağazanızın webhook URL'sini gösterir. Dostça URL'lerle şu biçimde görünür: https://your-shop/module/wcp_peach_pay/webhook; başında /en/ gibi bir dil kodu da olabilir. URL'yi ayarlarda gösterildiği gibi aynen kopyalayın. Peach Payments'tan (support@peachpayments.com) hesabınız için Card webhook'larını bu URL ile etkinleştirmesini isteyin, ardından aldığınız şifre çözme anahtarını aynı modun Webhook Decryption Key alanına girin.

Peach Payments her webhook'u şifreler (AES-256-GCM). Test veya canlı anahtarla şifresi çözülemeyen bir webhook reddedilir; bu nedenle siparişlerinizi yalnızca Peach Payments değiştirebilir. Bir modun anahtarıyla şifresi çözülen webhook yalnızca o modda başlatılan ödemelere uygulanır. Modül şu ödeme bildirimlerini kullanır:

Diğer bildirimler, örneğin webhook etkinleştirildiğinde gönderilen test bildirimi, ignored yanıtı alır. Webhook anahtarı olmadan bir sipariş, müşteri ödemeden sonra mağazaya döndüğünde oluşturulur.

Payment form

Card brands: Peach Payments formunda gösterilen markalar: Visa, Mastercard, American Express, Diners Club. Yalnızca Entity ID'niz için etkin olan markaları seçin. Varsayılan: Visa ve Mastercard. Hiçbir marka seçilmezse kaydetme bir uyarı gösterir ve form Visa ile Mastercard'ı gösterir.

Advanced

Logging: API isteklerini ve ödeme sonuçlarını modül klasöründeki logs/peach_p_debug.log.php dosyasına kaydeder. Dosya web üzerinden okunamaz. 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 girişlerini gösterir. Boşaltmak için Clear log düğmesine tıklayın.

Delete data on uninstall: açıkken modül kaldırıldığında modülün ayarları ve günlükleri silinir. Siparişlerin Peach Payments verileri (ödeme denemeleri, ödeme kimlikleri) ve sipariş durumları siparişlere ait olduğu için korunur. Varsayılan: kapalı.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Credit / Debit Card (Peach Payments)) ve siparişi onaylar. Test modunda ödeme yöntemi Test mode: no real payment will be made. ifadesini gösterir. Modül, sepet tutarı ve sepet para biriminde bir Peach Payments checkout'u hazırlar ve mağazanızın Peach Payments payment sayfasını, Peach Payments kart formu ve seçilen kart markalarıyla, Peach Payments destekliyorsa müşterinin dilinde gösterir. Test modunda sayfa Test mode: use a Peach Payments test card, no real payment will be made. ifadesini gösterir. Kart bilgileri Peach Payments formuna girilir ve form betiği Subresource Integrity özetiyle yüklenir. Choose another payment method bağlantısı ödeme adımına geri döner. Bu noktada henüz bir sipariş yoktur. Sayfa yenilendiğinde, sepet değişmediği sürece aynı checkout en fazla 25 dakika boyunca yeniden kullanılır.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Peach Payments onayladıktan sonra ödenmiş olarak işaretlenir: mağaza, bu sepetin checkout sonucunu checkout'un oluşturulduğu modda Peach Payments API'den okur ve ödemenin bu sepete ait olduğunu doğrular. Webhook da bağımsız olarak aynı işlemi yapar; hangisi önce gelirse siparişi oluşturur, diğeri hiçbir şey değiştirmez. Ardından müşteri standart sipariş onay sayfasını görür.

Ödeme tamamlanmazsa müşteri bir mesajla ödeme adımına döner ve tekrar deneyebilir: Payment failed: ardından Peach Payments'ın belirttiği neden ve Please try again or use another card., ya da The payment was not completed. Please try again. Sepet korunur. Sonuç henüz onaylanamıyorsa (örneğin Peach Payments yanıt vermediyse veya webhook tam o anda aynı sepeti işliyorsa), mesaj We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. olur. Ödemenin modu için bir webhook anahtarı ayarlanmamışsa müşteriden bunun yerine sizinle iletişime geçmesi istenir.

Ödeme formu hazırlanamazsa müşteri ödeme adımında kısa bir mesajla kalır: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (eksik veya hatalı kimlik bilgileri), bazı fatura bilgilerinin ödeme sağlayıcısı tarafından kabul edilmediğini belirten bir mesaj ya da The payment form could not be loaded. 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ün ödeme adımının kendisinde kart formu yoktur; kayıtlı kart, abonelik, ön provizyon ve sonradan tahsilat ile EFT, BNPL, QR veya kart dışı diğer yöntemler de yoktur.

Siparişler

Sipariş durumları

No order yet: müşteri ödeme yapmadı, ödeme reddedildi veya tamamlanmadı ya da Peach Payments henüz onaylamadı. Yalnızca sepet vardır ve müşteri yeniden ödeme yapabilir.

Payment accepted: ödeme onaylandı ve tutar ile para birimi sepetle eşleşiyor. Ödeme, Peach Payments ödeme kimliği işlem kimliği olarak kaydedilir; bir not Peach Payments sonuç kodunu, açıklamasını ve ödeme kimliğini gösterir. Peach Payments ödemeyi manuel incelemeye aldıysa not, göndermeden önce Peach Payments panelinde kontrol etmenizi ister.

Awaiting Peach Payments payment: Peach Payments, onay bekleyen bir ödeme bildirdi. Webhook daha sonra siparişi Payment accepted durumuna taşır ya da başarısız olarak işaretler.

Peach Payments payment on hold: ödenen tutar veya para birimi sepetten farklıdır (not: amount/currency mismatch — manual review required) ya da ödeme siparişin iptal edilmesinden sonra gelmiştir. Not, neyin kontrol edilmesi gerektiğini açıklar. Ödemeyi Peach Payments panelinde kontrol edin, ardından siparişi işleyin veya ödemeyi iade edin.

Payment error: Peach Payments, bekleyen siparişin beklediği ödemeyi reddetti. Reddedilen bir deneme, ödenmiş, beklemede veya iptal edilmiş bir siparişi hiçbir zaman değiştirmez.

Zaten ödenmiş bir siparişin ikinci ödemesi başarılı olursa sipariş değişmez. Bir not, bunun yinelenen bir ödeme olduğunu belirtir ve Peach Payments panelinden iade etmenizi ister. İade edilmiş bir sipariş için gelen ödeme yalnızca siparişe not edilir.

Peach Payments ödeme bloğu

Sipariş sayfasında ödeme kimliği, checkout kimliği, satıcı işlem kimliği, Peach Payments'a gönderilen tutar, sonuç ve sonuç kodu, test ödemeleri için bir Test mode rozeti ve siparişin Peach Payments notes bölümünün yer aldığı bir Peach Payments payment bloğu gösterilir.

İadeler

PrestaShop sipariş sayfasından iade yapılamaz. Ödemeyi Peach Payments panelinden iade edin ve gerekirse PrestaShop'ta kaydedin (kısmi iade veya kredi notu). Webhook kuruluysa Peach Payments'ta yapılan iadeler, iptaller ve chargeback'ler tutar ve kimlikle birlikte sipariş notlarına 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 Peach Payments Pay Gateway, Modules > Module Manager > VibeFox Peach Payments Pay 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ı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarih ve alan adınız) gösterir; ayrıca 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 düğmeleri bulunur. Bunların altında Product: presta-payment-peach satırı ile vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı yer alır. Anahtarı yalnızca modül için Configure yetkisi olan çalışanlar değiştirebilir. Bloktaki metinler 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 veya hesabınızda bir alan adı yuvası 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 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ı boşaltmaz. Yuvayı vibefox.net hesabınızdan boşaltın.

Etkin bir anahtar olmadan Peach Payments, müşterilere ödeme adımında 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 mağaza sayfası, 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 ayarlayabilirsiniz, ancak ödeme adımında test edemezsiniz. Modules > Module Manager bölümünde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler müşterinin dönüşü ve webhook ile onaylanmaya devam eder.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek yenileme gerektirir. Back office'te çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün günde bir, 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

Peach Payments ödeme adımında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu, geçerli modun Entity ID ve Access Token bilgilerinin girildiğini (test modunda Test Entity ID ve Test Access Token, canlı modda Live Entity ID ve Live Access Token) ve sepet para biriminin ZAR, KES veya MUR olduğunu kontrol edin. Ayarların üstündeki bildirimler sorunu belirtir. 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şmadı: müşteri mağazaya dönmedi ve webhook gelmedi. Peach Payments'ın Card webhook'larını tam olarak ayarlarda gösterilen URL için etkinleştirdiğini, ödemenin yapıldığı modun Webhook Decryption Key alanının girildiğini ve bir güvenlik duvarı ya da parola koruması URL'yi engellemediğini kontrol edin. Logging seçeneğini açın ve reddedilen webhook'lar için Log alanına bakın.

Webhook, Decryption failed yanıtı veriyor: webhook ne test ne de canlı anahtarla çözülebildi. Anahtar yanlış ya da başka bir hesaba veya moda ait. Bu webhook URL'si için Peach Payments'ın gönderdiği anahtarı girin.

Webhook, Webhook key not configured yanıtı veriyor: ne test ne de canlı webhook anahtarı ayarlı veya geçerli değil. 64 karakterlik anahtarı girin. Peach Payments webhook'u daha sonra tekrar gönderir.

Webhook, Busy, retry later yanıtı veriyor: sepet tam o sırada müşterinin dönüşü tarafından işleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Hiçbir şey değişmedi ve Peach Payments webhook'u tekrar gönderir. Günlük nedeni gösterir.

Webhook, Missing or malformed data yanıtı veriyor: istekte şifreli gövde ya da X-Initialization-Vector / X-Authentication-Tag başlıkları yoktu; örneğin bir proxy isteği değiştirdiği için. Hiçbir şey değişmedi.

Webhook, ignored yanıtı veriyor: bildirim gerçek ama bu mağazanın bir checkout'una ait değil (aynı Entity ID'ye sahip başka bir mağaza, silinmiş bir sepet) ya da ödemeden farklı bir moddan geldi. Hiçbir şey değişmedi.

Webhook URL'si tarayıcıda Method not allowed gösteriyor: bu normaldir. URL yalnızca Peach Payments'tan gelen istekleri kabul eder.

Müşteri The payment form is not available right now mesajını görüyor: geçerli modun Access Token'ı veya Entity ID'si hatalı. Kimlik bilgilerini ve modu kontrol edin, Peach Payments kodu için günlüğü okuyun.

Ödemeden sonra sipariş Peach Payments payment on hold durumunda: Peach Payments payment bloğundaki notları okuyun. Ödenen tutar veya para birimi sepetten farklıydı ya da ödeme siparişin iptal edilmesinden sonra geldi. Ödemeyi Peach Payments panelinde kontrol edin, ardından siparişi işleyin veya ödemeyi iade edin.

Kaydederken webhook anahtarının 64 karakterlik onaltılık anahtar olması gerektiği görünüyor: değer Peach Payments'tan gelen anahtar değil. Düzeltilene kadar webhook'lar çözülemez.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Peach Payments Pay 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 modülün ayarları ve günlükleri silinir. Kapalıysa tüm ayarlar sonraki yeniden kurulum için saklanır. Checkout denemeleri, ödeme kimlikleri ve Awaiting Peach Payments payment ile Peach Payments payment on hold sipariş durumları her zaman korunur. Mevcut siparişler ödeme notlarını, işlem kimliklerini ve Peach Payments checkout verilerini korur.

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