VibeFox Braintree for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

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

Braintree hesabı: Braintree hesabınızın Merchant ID, Public Key ve Private Key bilgilerine ihtiyacınız var. Bunları Braintree Control Panel'de (sandbox: sandbox.braintreegateway.com, canlı: www.braintreegateway.com) dişli simgesinin altında, API ve API Keys bölümlerinde bulabilirsiniz. Sandbox ve canlı hesapların anahtarları farklıdır. 3-D Secure değerini Disabled yapmadığınız sürece, 3-D Secure Braintree satıcı hesabınız için etkin olmalıdır. Webhook gerekmez: kart ödemeleri hemen onaylanır.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar yalnızca 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 Braintree Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. Braintree Control Panel'deki Merchant ID, Public Key ve Private Key bilgilerini sandbox veya canlı alanlarına kopyalayın.

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Sandbox mode açık kalsın ve bir Braintree sandbox test kartıyla deneme siparişi verin. Ardından gerçek ödemeleri canlı kimlik bilgileriyle almak için Sandbox mode seçeneğini kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Braintree payment authorized ve Braintree payment on hold. PrestaShop, tüm para birimleri, ülkeleri ve müşteri gruplarını kapsayan yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünden sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Braintree Gateway > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Ödeme yöntemi etkinken seçili ortamın Merchant ID, Public Key veya Private Key bilgisi eksikse, sayfa bunlar doldurulana kadar ödeme yönteminin ödeme sayfasında gizli olduğunu uyarır. Sandbox modu açıkken sayfa Sandbox mode is on: test payments, no real money. mesajını gösterir.

Braintree

Enable/Disable: Enable Braintree card payments ödeme yöntemini açar veya kapatır. Varsayılan: off.

Title: müşterilerin ödeme sayfasında gördüğü ödeme yöntemi adı. Siparişte kayıtlı ödeme yöntemi adı da budur. Varsayılan: Credit / debit card. Zorunlu.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely with your credit or debit card via Braintree.

API kimlik bilgileri

Braintree Control Panel'e (sandbox veya canlı) giriş yapın, dişli simgesine, ardından API ve API Keys bölümlerine tıklayın. Public ve Private Key orada listelenir; Merchant ID de aynı sayfada gösterilir. Sayfa yalnızca seçili ortamın kimlik bilgisi alanlarını gösterir; her iki takım da kayıtlı kalır.

Sandbox mode: Braintree sandbox'ını kullanır (test ödemeleri, gerçek para yok). Varsayılan: on. Gerçek ödemeleri canlı kimlik bilgileriyle almak için kapatın. İadeler, tahsilatlar ve iptaller her zaman siparişin ödendiği ortamı kullanır. Açıkken müşteriler ödeme yönteminin altında SANDBOX / TEST MODE — no real money is charged. mesajını görür.

Sandbox Merchant ID ve Live Merchant ID: sandbox veya canlı hesabın Merchant ID değeri.

Sandbox Public Key ve Live Public Key: bu hesabın public anahtarı.

Sandbox Private Key ve Live Private Key: bu hesabın private anahtarı. Kayıtlı private anahtarlar bir daha asla 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.

Sandbox merchant account ID(s) ve Live merchant account ID(s): isteğe bağlı. Braintree, satıcı hesabının para biriminde tahsilat yapar. Varsayılan satıcı hesabınızı kullanmak için boş bırakın; tek bir ID (örneğin mystore_EUR) ya da para birimi başına bir ID girin: EUR=mystore_EUR, USD=mystore_USD. Tahsil edilen para birimi sipariş para birimiyle eşleşmezse işlem otomatik olarak iptal edilir (void) ve müşteriden ücret alınmaz.

Clear saved private keys: Sandbox Private Key veya Live Private Key kutusunu işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödeme

Transaction type: kartın nasıl tahsil edileceği.

3-D Secure: 3-D Secure 2 (Güçlü Müşteri Kimlik Doğrulaması), EEA ve Birleşik Krallık'taki çoğu kart ödemesi için zorunludur. Braintree hesabınızda da etkin olmalıdır (ödemeler 3-D Secure yapılandırma hatasıyla başarısız olursa Braintree desteğiyle iletişime geçin).

3-D Secure sonucu, kart tahsil edilmeden önce yalnızca tarayıcıda değil, sunucuda da kontrol edilir.

Gelişmiş

Debug log: API çağrılarını ve ödeme adımlarını ayrıca modül klasöründeki logs/wc_btg_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Bu kapalı olsa bile hatalar her zaman kaydedilir. Günlük hiçbir zaman API anahtarlarını, kart veya müşteri verilerini içermez. Varsayılan: off.

Log: günlüğün boyutunu ve en son kayıtlarını 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 ağ geçidi ayarları ve günlük silinir. Braintree işlemleri, iadeler ve sipariş durumları her zaman korunur; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir, tahsil edilebilir veya iptal edilebilir. Varsayılan: off.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Credit / debit card) ve kartı, ödeme seçeneğinin içindeki Braintree formuna girer. Form yalnızca ödeme sayfasında Braintree'den yüklenir ve mağazanın dilini kullanır. 3-D Secure açıkken müşteri siparişi verirken bankasının doğrulamasını tamamlar; sepet toplamı, e-posta ve fatura adresi bu doğrulamaya iletilir.

Modül daha sonra tek kullanımlık jetonu, sepet toplamı için sepetin para biriminde Braintree API üzerinden tahsil eder ve Braintree'de sipariş kimliği olarak sepet numarasını kullanır. Bu noktaya kadar sipariş mevcut değildir. Tahsil edilen tutar ve para birimi sepetle karşılaştırılır. Sipariş, yalnızca Braintree ödemeyi kabul ettikten sonra oluşturulur ve müşteri PrestaShop'un standart sipariş onay sayfasını görür.

Ödeme başarısız olursa sipariş oluşturulmaz, nedeni modül günlüğüne yazılır ve müşteri bir mesajla birlikte ödeme adımında kalır; örneğin Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. veya The card security code or billing address could not be verified. Please check your details and try again. Müşteri hemen yeniden deneyebilir. Tahsil edilen para birimi veya tutar sepetle eşleşmezse işlem iptal edilir (void) ve müşteri This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us. mesajını görür.

Bir sepetten asla iki kez tahsilat yapılmaz. Ödeme işlenirken ikinci bir gönderim This order is already being paid. Please wait a moment and check your e-mail before trying again. mesajını gösterir. Kart tahsil edilmiş ama PrestaShop siparişi oluşturamamışsa müşteri Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. mesajını görür. Aynı sepet için bir sonraki deneme, kayıtlı işlemden siparişi yeniden tahsilat yapmadan oluşturur.

Modül yalnızca kart ödemelerini kabul eder. Kayıtlı kart, abonelik veya tekrarlayan ödeme yoktur; PayPal, Venmo, Apple Pay, Google Pay ya da yerel ödeme yöntemleri desteklenmez ve Braintree webhook'ları kullanılmaz.

Siparişler ve iadeler

Sipariş durumları

Henüz sipariş yok: ödeme yapılmadı veya reddedildi. Yalnızca sepet mevcut.

Payment accepted: kart tahsil edildi (Sale) veya bir yetkilendirme tahsil edildi. Ödeme, Braintree işlem kimliğiyle kaydedilir; siparişin mesajlarındaki özel bir not tutarı, işlem kimliğini ve 3-D Secure sonucunu gösterir.

Braintree payment authorized: tutar yalnızca yetkilendirildi (Authorize only). Siz tahsil edene kadar hiçbir ödeme kaydedilmez.

Braintree payment on hold: Braintree beklenmeyen bir işlem durumu döndürdü veya yanlış para biriminde ya da yanlış tutarda bir tahsilat otomatik olarak iptal edilemedi. Not, Braintree Control Panel'de neyin kontrol edileceğini açıklar.

Canceled: bir yetkilendirme iptal edildi.

Refunded: ödeme modül üzerinden tamamen iade edildi.

Zaten oluşturulmuş bir siparişe başka bir işlem gelirse sipariş değişmez. Bir not, bunu Braintree Control Panel'de kontrol edip iptal etmenizi veya iade etmenizi ister.

Braintree payment bloğu

Sipariş sayfasında, işlem kimliğini (ilgili ortamın Braintree Control Panel'indeki işleme bağlantılı), işlem durumunu, tutarı ve satıcı hesabını, 3-D Secure sonucunu, tahsil edilen ve iade edilen tutarı, sandbox ödemeleri için bir Sandbox rozetini ve iade geçmişini gösteren Braintree payment bloğu bulunur. Bloktaki düğmeler siparişleri düzenleme yetkisi gerektirir; Modules sayfalarına erişim gerekmez.

Tahsilat ve iptal

Braintree payment authorized durumundaki bir sipariş için, sipariş tutarını tahsil etmek üzere Capture Braintree payment düğmesine, tutulan tutarı serbest bırakmak için Void Braintree authorization düğmesine tıklayın. Tahsilat siparişi Payment accepted durumuna getirir ve ödemeyi kaydeder; iptal siparişi Canceled durumuna getirir. İşlem başarısız olursa hata blokta gösterilir ve sipariş notlarına eklenir.

İadeler

Braintree payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Braintree düğmesine tıklayın. Refund this amount through Braintree? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. İadeler, Braintree'nin tahsil ettiği tutar ve para biriminde yapılır; bu nedenle tutar veya para birimi uyuşmazlığından sonra en fazla müşterinin gerçekten ödediği tutara kadar iade yapabilirsiniz. Braintree yalnızca mutabakatı tamamlanmış işlemleri iade eder, genellikle 24 saat içinde. Mutabakattan önce tam iade iptal (void) olarak yapılır; kısmi iade ise mutabakatı beklemeniz gerektiğini belirten bir mesajla başarısız olur. İade, ödemenin ortamına (sandbox veya canlı) gönderilir; bu nedenle o ortamın kimlik bilgileri girilmiş olmalıdır. Braintree iadeyi kabul etmezse blok hatayı gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir; kısmi iade durumu değiştirmez.

Modül kredi notları oluşturmaz. Sipariş sayfasındaki PrestaShop'un standart iade düğmeleri Braintree üzerinden para geri göndermez. İtirazlar (chargeback), mutabakat reddleri ve Braintree Control Panel'de yapılan iadeler PrestaShop ile senkronize edilmez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Braintree Gateway lisans bloğu, Modules > Module Manager > VibeFox Braintree 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ı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarihi ve alan adınızı) ve 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üğmelerini gösterir. Bunların altında Product: presta-payment-braintree satırı ile 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 yetkisine sahip çalışanlar değiştirebilir. Bloktaki metinler yönetim paneli 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 ya da 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 yalnızca bir alan adında çalışır: ana mağazanın alan adında, çoklu mağaza kurulumunda da öyle. 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 Braintree, ö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 yönetim paneline giriş yaptığınızı bilmediği için ödeme yöntemi sizden de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme sayfasında test edemezsiniz. Modules > Module Manager bölümünde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: daha önce başlatılmış ödemeler yine onaylanır ve tahsilatlar, iptaller ve iadeler çalışmaya devam eder.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Yönetim panelinde çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, ardından 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

Braintree ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve seçili ortamda Merchant ID, Public Key ve Private Key bulunduğunu kontrol edin. Ayarlar sayfası, bir anahtar eksik olduğunda 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.

Kart tahsil edildi, ama sipariş oluşturulmadı: kart ödemeleri webhook olmadan hemen onaylanır. Modül sayfasındaki Log alanına bakın. Günlük Braintree'nin yanıtının kaybolduğunu söylüyorsa, başka bir ödeme kabul etmeden önce Braintree Control Panel'de sipariş kimliği olarak sepet numarasını içeren bir işlem olup olmadığını kontrol edin. Tahsilattan sonra sipariş oluşturulamadıysa, aynı sepet için bir sonraki ödeme denemesi siparişi yeniden tahsilat yapmadan oluşturur.

Kart formu Could not initialize payment form mesajını gösteriyor: seçili ortamın anahtarları yanlış ya da satıcı hesabı kimliği bu hesapta mevcut değil. Anahtarları ve satıcı hesabı kimliklerini kontrol edin, ardından sayfayı yeniden yükleyin.

3-D Secure tüm ödemelerde başarısız oluyor: 3-D Secure, Braintree satıcı hesabınız için etkin olmalıdır. Braintree desteğiyle iletişime geçin veya 3-D Secure seçeneğini Disabled yapın (EEA ve Birleşik Krallık'ta önerilmez; orada SCA zorunludur).

Müşteriye, ödemenin sipariş para biriminde işlenemediği bildiriliyor: Braintree, satıcı hesabının para biriminde tahsilat yaptı. Sepet para birimi için satıcı hesabı kimliğini, mevcut ortamın satıcı hesabı alanına girin.

Müşteri The order total must be greater than zero to pay by card mesajını görüyor: sepet toplamı sıfır, örneğin bir kupon uygulandıktan sonra. Bu tür siparişler kartla ödenemez.

Kısmi iade, ödemeden hemen sonra başarısız oluyor: Braintree yalnızca mutabakatı tamamlanmış işlemleri iade edebilir, genellikle 24 saat içinde. İşlemi şimdi iptal etmek için tutarın tamamını iade edin veya kısmi iadeyi mutabakattan sonra yapın.

İade, tahsilat veya iptal ortamla ilgili bir mesajla başarısız oluyor: ödeme sandbox veya canlı ortamda yapıldı ve o ortamın kimlik bilgileri girilmemiş. Bunları girin ve yeniden deneyin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Braintree 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 ağ geçidi ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki yeniden kurulum için saklanır. Braintree işlemleri ve iadeleri ile Braintree payment authorized ve Braintree payment on hold sipariş durumları her zaman korunur; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir, tahsil edilebilir veya iptal edilebilir. Mevcut siparişler, ödeme notlarını ve işlem kimliklerini korur.

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