VibeFox PagSeguro for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x.

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

Para birimi: Brezilya reali (BRL). Ödeme yöntemi yalnızca BRL sepetler için gösterilir.

HTTPS: PagBank'ın ödeme bildirimlerini gönderebilmesi için mağazanıza internetten HTTPS ile erişilebilmelidir.

PagBank hesabı: gerçek ödemeler için bir canlı token ve testler için bir sandbox token'ı. Canlı: PagBank hesabınıza giriş yapın, Venda online > Integrações bölümünü açın ve Gerar token düğmesine tıklayın; PagBank token'ı e-posta ile gönderir. Sandbox: PagBank geliştirici portalında bir sandbox hesabı oluşturun ve onun token'ını kopyalayın. Sandbox ve canlı token'lar yalnızca kendi ortamlarında çalışır.

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 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 PagSeguro Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. Sandbox token'ını ve gerçek ödemeleri almak için canlı token'ı girin.

5. Enable / Disable seçeneğini açın ve Save düğmesine tıklayın. Sandbox Mode açıkken test ödemeleri yapın, ardından gerçek ödemeleri almak için kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting PagBank payment ve PagBank payment on hold. PrestaShop, yeni ödeme modülünü tüm para birimleri, ülkeler ve müşteri grupları için sunar. Bunları Payment > Preferences bölümünden sınırlayabilirsiniz; BRL para biriminin modül için izinli kalması gerekir.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox PagSeguro 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 geçerli modu gösterir: SANDBOX MODE (ödemeler PagBank sandbox'ında oluşturulur, gerçek tahsilat yapılmaz) veya LIVE (ödemeler canlı token ile oluşturulur). Geçerli modun token'ı eksikse uyarır (bu durumda ödeme yöntemi ödeme sürecinde gizlenir); mağazanın varsayılan para birimi BRL değilse de uyarır (bu durumda ödeme yöntemi diğer para birimlerindeki sepetler için sunulmaz).

PagSeguro / PagBank

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

Title: müşterilerin ödeme sürecinde gördüğü ödeme yöntemi adı. Siparişte de ödeme yönteminin adı olarak kaydedilir. Varsayılan: PagSeguro / PagBank. Zorunlu.

Description: ödeme sürecinde ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

PagBank hesabı

Bu bölüm token'ların nereden alınacağını açıklar ve PagBank hesabınıza ile token hakkındaki PagBank sayfasına bağlantılar içerir.

Sandbox Mode: Enable sandbox/test mode (no real charges). Yeni ödemeler sandbox token'ı ile PagBank sandbox'ına gider; müşteriler ödeme yönteminin altında SANDBOX MODE — Using test environment. No real charges. ifadesini görür. Bir siparişin durum sorgulamaları ve iadeleri her zaman ödemenin oluşturulduğu ortamı ve token'ı kullanır. Varsayılan: açık.

Sandbox token: PagBank sandbox token'ı. Sandbox modu açıkken kullanılır.

Production token: PagBank canlı token'ı (Bearer). Sandbox modu kapalıyken kullanılır. Gizli tutun.

Kaydedilmiş token'lar 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 tokens: bir token'ı işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödeme bildirimleri

Notification URL: her ödeme, PagBank'a durum değişikliklerini nereye bildireceğini söyler; bu nedenle PagBank'ta yapılandırılacak bir şey yoktur. Bölüm URL'yi gösterir. Dostu URL'lerle şöyle görünür: https://your-shop/module/wcp_pagseguro_gateway/webhook. Adresin internetten HTTPS ile erişilebilir olması gerekir.

x-authenticity-token başlığı taşıyan bildirimler, ödemenin oluşturulduğu ortamın token'ı ile kontrol edilir; geçersiz imza reddedilir. Bildirimin gövdesi asla güvenilir kabul edilmez: modül, bir sipariş oluşturulmadan veya değiştirilmeden önce her zaman PagBank API'sinden ödeme sayfasını ve PagBank siparişini (durum, tutar, para birimi) okur. Bildirim olmadan sipariş, müşteri ödemeden sonra mağazaya döndüğünde oluşturulur.

Gelişmiş

Debug log: Log API requests and notifications ayrıntıları modül klasöründeki logs/wc_psg_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Günlükler token veya müşteri verisi içermez. Hatalar her zaman kaydedilir. 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çıksa modül kaldırıldığında ağ geçidi ayarları ve günlük silinir. Siparişler, PagBank referansları (iadeler için gerekli) ve sipariş durumları her zaman korunur. Varsayılan: kapalı.

Ödeme süreci

Ödeme adımında müşteri ödeme yöntemini (varsayılan olarak PagSeguro / PagBank) seçer ve onaylar. Modül, sepet toplamı için BRL cinsinden tek bir ürün olarak Order # ile sepet numarasını ve mağaza adınızı içeren bir PagBank ödemesi oluşturur ve müşteriyi PagBank ödeme sayfasına yönlendirir. Mağazada mevcutsa müşterinin adı ve e-postası ile adresteki Identification number veya VAT number alanındaki CPF ya da CNPJ ve bir Brezilya telefon numarası doldurulur; müşteri bunları PagBank sayfasında tamamlayabilir veya düzeltebilir. Müşteri, PagBank hesabınızda etkin olan yöntemlerle (örneğin kredi kartı, PIX veya boleto) öder. Ödeme sayfasının süresi 120 dakikada dolar. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca PagBank ödemeyi onayladıktan sonra ödenmiş olarak işaretlenir: modül, bildirim geldiğinde veya müşteri döndüğünde ödemeyi PagBank API'sinden okur ve yalnızca geri dönüş hiçbir zaman bir siparişi ödenmiş olarak işaretlemez. Sipariş daha sonra oluşturulur ve müşteri Your payment with PagBank has been received. ifadesiyle sipariş onay sayfasını görür. Oluşturulan bir boleto veya PIX ya da analizdeki bir ödeme için sayfa Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. ifadesini gösterir. Böyle bir ödeme sonradan reddedilir veya iptal edilirse sayfa Your PagBank payment was not completed. Please contact us about this order. ifadesini gösterir. Müşteri döndüğünde PagBank ödemeyi henüz onaylamadıysa Payment confirmation sayfası görünür; bu sayfa We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. ifadesini ve Check again düğmesini gösterir.

Ödeme tamamlanmadıysa müşteri ödeme sürecine şu mesajlarla döner: The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. veya The payment was declined by PagBank. Please try again with another card or payment method. Sepet korunur. Boleto veya PIX bekleyen bir sipariş iptal edildiyse müşteri The PagBank payment was cancelled, so the order was cancelled. mesajını görür.

Müşteri yeniden ödeme yaptığında, tutar ve ortam aynıysa ve 10 dakika içinde dolmuyorsa açık PagBank ödemesi yeniden kullanılır. Aksi halde önceki ödeme devre dışı bırakılır ve artık ödenemez. Daha önce önceki sayfada yapılmış bir ödeme hâlâ sepet için geçerlidir ve yeni bir ödeme yerine sipariş oluşturulur.

PagBank ödemeyi başlatamazsa müşteri ödeme sürecinde kalır ve kısa bir mesaj görür; örneğin PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. veya Could not connect to PagBank. Please try again in a moment. Teknik neden günlüğe yazılır.

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

Modülde mağaza içi kart formu, kayıtlı kart, abonelik veya yinelenen ödeme, bölünmüş ödeme ve pazar yeri özelliği yoktur. Ödeme yöntemleri ve taksitler PagBank hesabınızda yapılandırılmış olanlardır.

Siparişler ve iadeler

Sipariş durumları

Henüz sipariş yok: müşteri PagBank'a yönlendirildi ve ödeme yapmadı, kart reddedildi veya ödeme sayfasının süresi doldu. Yalnızca sepet vardır ve müşteri yeniden ödeme yapabilir.

Payment accepted: ödeme beklenen tutar ve para birimiyle onaylandı. Ödeme, PagBank tahsilat kimliği (charge ID) işlem kimliği olarak kaydedilir ve bir not tutarı, ödeme yöntemini ve charge ID'yi gösterir.

Awaiting PagBank payment: bir boleto veya PIX oluşturuldu ve ödeme bekliyor ya da ödeme analizde. PagBank ödemeyi ödenmiş olarak bildirdiğinde sipariş Payment accepted durumuna geçer.

PagBank payment on hold: PagBank, sepetten farklı bir tutar veya para birimi bildirdi (örneğin ödeme sayfası oluşturulduktan sonra sepet değiştirildi), sipariş iptal edildikten sonra bir ödeme geldi (stoku kontrol edin, ardından siparişi tamamlayın veya ödemeyi PagBank'ta iade edin) ya da bir kart ödemesi yetkilendirildi ama tahsil edilmedi (PagBank'ta tahsil edin). Not bunu açıklar. Gerçekte alınan para siparişte kaydedilir.

Payment error: beklemede olan veya analizdeki bir ödeme reddedildi.

Canceled: süresi dolmuş bir boleto veya PIX gibi beklemedeki bir ödeme iptal edildi.

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

Her PagBank durumu bir kez uygulanır; bu nedenle tekrarlanan bildirimler veya geri dönüşler not veya durum değişikliği eklemez. Zaten ödenmiş bir sipariş için ikinci bir ödeme gelirse sipariş değiştirilmez ve bir not, kopya ödemeyi PagBank'ta iade etmenizi ister.

«PagBank payment» bloğu

Sipariş sayfasında PagBank checkout'u, PagBank sipariş ve tahsilat kimlikleri, ödeme yöntemi, durum, ödenen ve iade edilen tutar, sandbox ödemeleri için bir Sandbox rozeti, iade geçmişi ve siparişin PagBank notes bölümünü gösteren bir PagBank payment bloğu bulunur.

İadeler

PagBank payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via PagBank düğmesine tıklayın. Refund this amount through PagBank? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; Modules sayfalarına erişim gerekmez. Sınır, PagBank'ın tahsil ettiği tutardır; bu nedenle bir tutar uyuşmazlığından sonra sipariş toplamına değil, müşterinin gerçekte ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı ortamda ve token ile gönderilir. İade yalnızca PagBank onayladığında kaydedilir; aksi halde blok hatayı gösterir, örneğin PagBank refund failed: ... veya PagBank did not confirm the refund, ve hiçbir şey kaydedilmez. Boleto ödemelerinin iadeleri ve PIX'in kısmi iadeleri PagBank kurallarını izler. Başarılı bir iade, charge ID ile birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir; kısmi iade durumu değiştirmez. İadeler, PagBank ödemeyi ödenmiş olarak bildirdikten sonra kullanılabilir.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri PagBank üzerinden para geri göndermez.

PagBank panelinde yapılan iadeler bir sonraki bildirimle fark edilir: tam iade siparişi Refunded durumuna getirir, kısmi iade iade edilen tutarla birlikte bir not ekler ve iadeyi siparişe elle ekleyebilirsiniz.

Lisans anahtarı

Modül, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. Modules > Module Manager > VibeFox PagSeguro Gateway > Configure sayfasında, ayarların üstündeki ilk blok lisans bloğudur: License — VibeFox PagSeguro Gateway. 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 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-pagseguro satırı ve 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 yetkisine sahip personel 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 tarihli License expired on. Mağaza adresi değiştikten veya hesabınızda bir alan adı yuvası serbest bırakıldı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, çok mağazalı kurulumda da öyle. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızda serbest bırakın.

Etkin bir anahtar olmadan PagBank, ödeme sürecinde müşterilere gösterilmez. Ödeme yine de 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ı bilmediği için ödeme yöntemi sizden de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ama ödeme sürecinde 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 yine onaylanır ve iadeler çalışır.

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, ardından haftada bir. Cron job gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

PagBank ödeme sürecinde görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu, geçerli modun token'ının ayarlandığını (sandbox modunda Sandbox token, canlı modda Production token) ve sepet para biriminin BRL olduğunu kontrol edin. Ayarlar sayfası, token eksik olduğunda veya mağaza para birimi BRL olmadığında uyarı gösterir. Payment > Preferences bölümünde modülün BRL, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin.

Ödeme yapıldı ama sipariş oluşturulmadı: PagBank ödemeyi henüz bildirmedi ve müşteri mağazaya dönmedi. Bildirim geldiğinde sipariş hemen oluşturulur. Mağazanızın Notification URL adresinde HTTPS ile internetten erişilebilir olduğunu kontrol edin ve bildirimleri görmek için Debug log seçeneğini açın.

Bildirim Invalid signature yanıtını veriyor: x-authenticity-token, ödemenin yapıldığı ortamın token'ı ile eşleşmiyor veya bu token kayıtlı değil. Ayarlarda doğru token'ın bulunduğunu kontrol edin.

Bildirim Verification failed, retry later yanıtını veriyor: PagBank API'sine ulaşılamadı, ödemenin ortamının token'ı eksik ya da sepet aynı anda başka bir istek tarafından işleniyordu. PagBank bildirimi yeniden dener.

Bildirim Order not found yanıtını veriyor: bildirim, bu mağazada bu modülle ödenmemiş bir sepete ait. Hiçbir şey değiştirilmez.

Müşteri şu mesajı görür: PagBank payments are temporarily unavailable. Please choose another payment method.: geçerli modun token'ı eksik veya PagBank onu reddetti.

Müşteri şu mesajı görür: PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: sepet başka bir para biriminde.

Sipariş PagBank payment on hold durumunda: PagBank payment bloğundaki notları okuyun (Sipariş durumlarına bakın), PagBank'taki tutarları karşılaştırın, ardından siparişi tamamlayın veya ödemeyi iade edin.

İade token ile ilgili bir mesajla başarısız oluyor: ödeme sandbox'ta veya canlı ortamda yapıldı ve o ortamın token'ı eksik ya da reddedildi. Doğru token'ı girin ve yeniden deneyin.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox PagSeguro 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 bir yeniden kurulum için saklanır. Siparişlerin PagBank ödemeleri ve iadeleri ile Awaiting PagBank payment ve PagBank payment on hold sipariş durumları her zaman korunur; böylece daha önce ödenen siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

PagSeguro ve PagBank, ilgili sahiplerinin ticari markalarıdır. Bu modül PagSeguro veya PagBank ile bağlantılı değildir ve onlar tarafından onaylanmamıştır.