VibeFox PagSeguro for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

Para birimi: Brezilya reali (BRL). Mağazanın para birimi (veya Pay for order sayfasında siparişin para birimi) BRL değilse ödeme yöntemi ödeme sayfasında gizlenir.

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

PagBank hesabı: gerçek ödemeler için bir canlı token ve testler için bir sandbox token'ı. Canlı token: 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 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. WordPress'te Plugins > Add New > Upload Plugin yolunu izleyin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_pagseguro_gateway klasörünü FTP ile /wp-content/plugins/ dizinine yükleyebilirsiniz.

2. Activate düğmesine tıklayın.

3. Ayarları açın: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage ya da Plugins 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. Sandbox token'ını ve gerçek ödemeleri kabul etmek için canlı token'ı girin.

6. Enable / Disable seçeneğini açın ve kaydedin. Sandbox Mode açıkken test ödemeleri yapın, ardından gerçek ödemeleri almak için kapatın.

Yapılandırma

Tüm ayarlar tek bir sayfada bulunur: WooCommerce > Settings > Payments > PagSeguro / PagBank. Sayfa başlığının altında geçerli modu gösterir: SANDBOX MODE (ödemeler PagBank sandbox ortamında oluşturulur, gerçek tahsilat yapılmaz) veya LIVE (ödemeler canlı token ile oluşturulur). Geçerli modun token'ı eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve mağaza para birimi BRL değilse uyarır. Ödeme yöntemleri listesinde, geçerli modun token'ı girilene kadar PagBank kurulum gerektiriyor olarak işaretlenir; sandbox modu açıkken ise bir test modu rozeti gösterilir.

Genel

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

Title: müşterilerin ödeme sayfasında gördüğü ödeme yöntemi adı. Varsayılan: PagSeguro / PagBank.

Description: ödeme sayfasında ö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 konusundaki PagBank sayfasına bağlantılar içerir.

Sandbox Mode: Enable sandbox/test mode (no real charges). Yeni ödemeler sandbox token'ı ile PagBank sandbox ortamına gider ve ödeme sayfasında SANDBOX MODE notu gösterilir. Bir siparişin durum sorguları ve iadeleri her zaman, o siparişin ödemesinin 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'ı. Sandbox modu kapalıyken kullanılır. Gizli tutun.

Sürüm 1.0'daki tek token otomatik olarak taşınır: sandbox modu açıksa sandbox token'ı olur, aksi halde canlı token olarak kalır.

Ödeme bildirimleri

Her ödeme, PagBank'a durum değişikliklerini nereye bildireceğini söyler; bu yüzden PagBank'ta yapılandırılacak bir şey yoktur. Bölüm bildirim URL'sini gösterir. Şu biçimdedir: https://your-site/wc-api/webhook_wc_pagseguro/. Adresin internetten HTTPS ile erişilebilir olması gerekir.

x-authenticity-token başlığı taşıyan bildirimler, siparişin ortamının token'ı ile doğrulanır; geçersiz imza reddedilir. Bildirimin gövdesi hiçbir zaman güvenilir kabul edilmez: eklenti, siparişi değiştirmeden önce ödeme sayfasını ve PagBank siparişini her zaman PagBank API'sinden (durum, tutar ve para birimi) okur.

Gelişmiş

Debug log: Log API requests and notifications ayrıntıları WooCommerce > Status > Logs altına, wcp_pagseguro_gateway kaynağıyla yazar. Hatalar her zaman kaydedilir. Günlükler token veya müşteri verisi içermez. Varsayılan: kapalı.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Varsayılan: kapalı.

Ödeme sayfası

Müşteri ödeme yöntemini seçer (varsayılan olarak PagSeguro / PagBank) ve siparişi verir. Eklenti, siparişin tam toplamı için BRL cinsinden tek bir kalem olarak bir PagBank ödemesi oluşturur; kalem adı Order #, ardından sipariş numarası ve mağazanızın adı olur. Ardından müşteriyi PagBank ödeme sayfasına yönlendirir. Müşterinin adı ve e-posta adresi, Brazilian Market on WooCommerce eklentisinin alanlarından gelen CPF veya CNPJ ve bir Brezilya telefon numarası, mağazada mevcutsa doldurulur; müşteri bunları PagBank sayfasında tamamlayabilir veya düzeltebilir. Müşteri, PagBank hesabınızda etkin olan yöntemlerle öder; örneğin kredi kartı, PIX veya boleto.

Ödeme sayfası, ödenmemiş siparişi WooCommerce Hold stock zamanlayıcısı iptal etmeden 5 dakika önce sona erer (en az 10 dakika); stok ayrılmıyorsa ise 120 dakika sonra sona erer.

Ödemeden sonra müşteri mağazaya döner. Bu dönüş, bir bildirimle aynı şekilde kontrol edilir: eklenti ödemeyi PagBank API'sinden okur ve yalnızca dönüş hiçbir zaman bir siparişi ödenmiş olarak işaretlemez. Ödenmiş bir sipariş veya bekleyen bir ödeme (boleto, PIX, analiz) sipariş alındı sayfasına götürür; PagBank henüz bildirmemişse sipariş bildirimle onaylanır.

Ödeme tamamlanmadıysa müşteri Pay for order sayfasına döner ve şu mesajlardan biriyle karşılaşır: 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. Ödeme iptal edilmiş ve sipariş de onunla birlikte iptal edilmişse müşteri The PagBank payment was cancelled, so the order was cancelled. mesajıyla sepete yönlendirilir.

Müşteri yeniden ödeme yaptığında, tutar ve ortam aynıysa ve 10 dakika içinde sona ermeyecekse açık PagBank ödemesi yeniden kullanılır. Aksi halde önceki ödeme devre dışı bırakılır ve artık ödenemez. Bundan önce önceki sayfada yapılmış bir ödeme siparişe hâlâ sayılır.

PagBank ödemeyi başlatamazsa müşteri 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. PagBank'ın belirttiği neden sipariş notlarına eklenir.

Ödeme yöntemi klasik ödeme sayfasında, Checkout bloğunda ve Pay for order sayfasında çalışır. WooCommerce High-Performance Order Storage (HPOS) ile uyumludur.

Eklentinin site üzerinde 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ılanlardır.

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri PagBank'a yönlendirildi ve henüz ödeme yapmadı. Bir notta PagBank ödeme kimliği ve ortam gösterilir. Ödeme sayfası ödeme yapılmadan sona ererse bir not bunu bildirir ve durum değişmez.

Processing: ödeme onaylandı. Bu, ödemeden sonraki standart WooCommerce durumudur; yalnızca sanal indirilebilir ürün içeren siparişler Tamamlandı olur. Sipariş notunda tutar, ödeme yöntemi ve siparişin işlem kimliği de olan PagBank tahsilat kimliği gösterilir.

On hold: bir boleto veya PIX oluşturuldu ve ödeme bekleniyor; ödeme analizde; bir kart ödemesi yetkilendirildi ama tahsil edilmedi (PagBank'ta tahsil edin); ödenen tutar veya para birimi siparişle eşleşmiyor; ya da WooCommerce ödenmemiş siparişi iptal ettikten sonra bir ödeme geldi (stoku kontrol edin, ardından siparişi tamamlayın veya ödemeyi PagBank'ta iade edin). Sipariş notu durumu açıklar.

Failed: ödeme reddedildi. Müşteri Pay for order sayfasından yeniden ödeme yapabilir.

Cancelled: ödeme iptal edildi; örneğin süresi dolmuş bir boleto veya PIX.

Refunded: ödeme PagBank panelinde tamamen iade edildi.

Her PagBank durumu yalnızca bir kez uygulanır; bu nedenle tekrarlanan bildirimler veya dönüşler yeni not, e-posta veya stok düşümü oluşturmaz. Zaten ödenmiş bir sipariş için ikinci bir ödeme gelirse bir not, bunu PagBank'ta iade etmenizi ister.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via PagSeguro / PagBank düğmesine tıklayın (düğme ödeme yönteminizin başlığını gösterir). Tam ve kısmi iadeler desteklenir. İade, ödemenin yapıldığı ortamda ve token ile gönderilir. İade yalnızca PagBank onayladığında kaydedilir; aksi halde WooCommerce 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, tahsilat kimliğiyle birlikte sipariş notlarına eklenir.

PagBank panelinde yapılan iadeler WooCommerce iade satırı olarak içe aktarılmaz. Tam iade siparişi İade edildi olarak ayarlar; kısmi iade ise iade edilen tutarı içeren bir not ekler ve iadeyi siparişe elle ekleyebilirsiniz.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Payments > PagSeguro / PagBank 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 gösterir; örneğin lisansın etkin olduğu tarih ve alan adınız. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu siteden kaldırmak için Remove key kullanın. Manage licenses and domains in your account bağlantısı vibefox.net hesabınızı açar.

Bir anahtar bir alan adında çalışır. Anahtarı bir siteden kaldırmak, o alan adının yerini serbest bırakmaz. Yeri vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan PagBank müşterilere ödeme sayfası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. Oturum açmış mağaza yöneticileri ödeme yöntemini hâlâ (unlicensed — visible to admins only) işaretiyle görür; böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Eklentiler sayfasında ve WooCommerce sayfalarında 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ı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

PagBank ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu, geçerli modun token'ının girildiğini (sandbox modunda Sandbox token, canlı modda Production token) ve mağaza para biriminin BRL olduğunu kontrol edin. Ayarlar sayfası bu durumların her birinde uyarı gösterir.

Ödeme gerçekleşti ama sipariş Ödeme bekleniyor durumunda kaldı: PagBank ödemeyi henüz bildirmedi ve müşteri mağazaya geri dönmedi. Bildirim geldiğinde sipariş güncellenir. Sitenizin internetten HTTPS ile erişilebilir olduğunu kontrol edin ve WooCommerce > Status > Logs bölümünde wcp_pagseguro_gateway kaynağına bakın.

Bildirim Invalid signature yanıtı veriyor: x-authenticity-token, siparişin ödendiği ortamın token'ı ile eşleşmiyor. Ayarlarda doğru token'ın bulunduğunu kontrol edin.

Bildirim Verification failed, retry later yanıtı veriyor: PagBank API'sine ulaşılamadı, siparişin ortamının token'ı eksik ya da sipariş aynı anda başka bir istekle güncelleniyordu. PagBank bildirimi yeniden dener.

Bildirim Order not found yanıtı veriyor: sipariş bu mağazada yok ya da başka bir ödeme yöntemiyle ödenmiş. Hiçbir şey değişmez.

Müşteri This order is already being processed mesajını görüyor: bir bildirim veya müşterinin dönüşü siparişi aynı anda güncelliyordu. Müşteri birkaç saniye sonra tekrar deneyebilir.

Müşteri PagBank payments are temporarily unavailable mesajını görüyor: geçerli modun token'ı eksik ya da PagBank tarafından reddedildi.

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

Sipariş Amount/currency does not match notuyla On hold durumunda: PagBank, tutarı veya para birimi sipariş toplamından farklı bir ödeme bildirdi; örneğin ödeme sayfası oluşturulduktan sonra sipariş düzenlendiği için. PagBank'taki tutarları karşılaştırın ve siparişi elle tamamlayın ya da iade edin.

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

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

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Kaldırmak için eklentiyi devre dışı bırakın ve Plugins sayfasından silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman silinir. Ağ geçidi ayarları, eklentinin diğer seçenekleri ve günlükleri yalnızca Delete Data on Uninstall açıksa silinir. Aksi halde yeniden kurulum için saklanır. Mevcut siparişler ödeme notlarını, işlem kimliklerini ve PagBank verilerini korur.

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