VibeFox Pagar.me for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

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

Pagar.me hesabı: Pagar.me hesabınızın gizli anahtarlarına ihtiyacınız vardır: test anahtarı (sk_test_...) ve canlıya geçmek için canlı anahtar (sk_...). Bunlar Pagar.me panelinde Development > Keys altındadır. Yalnızca gizli anahtarlar kullanılır; genel anahtar (pk_...) gerekli değildir. Yalnızca Pagar.me hesabınızda etkinleştirilmiş ödeme yöntemleri sunulabilir.

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_pagarme_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 > Pagar.me > Manage, ya da Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

4. Sayfanın üstündeki lisans bloğuna VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın.

5. Test gizli anahtarını ve canlıya geçtiğinizde canlı gizli anahtarı girin.

6. Pagar.me panelinde, ayarlarda gösterilen URL ile bir webhook oluşturun (bkz. Yapılandırma).

7. Enable / Disable seçeneğini açın ve kaydedin. Test 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 > Pagar.me. Başlığın altında sayfa geçerli modu gösterir: TEST MODE (ödemeler test gizli anahtarıyla oluşturulur, gerçek tahsilat yapılmaz) veya LIVE. Geçerli modun gizli anahtarı eksik olduğunda (bu durumda ödeme yöntemi ödeme sayfasında gizlenir), test anahtarı sk_test_ ile başlamadığında, canlı anahtar sk_ ile başlamadığında veya bir test anahtarı olduğunda ve mağaza para birimi BRL değilse uyarı verir. Ödeme yöntemleri listesinde, geçerli modun anahtarı girilene kadar Pagar.me kurulum gerektiren olarak işaretlenir; test modu açıkken bir test modu rozeti gösterilir.

Genel

Enable / Disable: Enable Pagar.me 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: Pagar.me.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API anahtarları

Gizli anahtarları Pagar.me panelinden kopyalayın: Development > Keys. Pagar.me, test ve canlı ödemeler için tek bir API adresi kullanır; bir ödemenin test mi yoksa gerçek mi olduğunu anahtar belirler.

Test mode: Use the test secret key (no real charges). Test modu açık olduğunda ödeme sayfasında TEST MODE notu gösterilir. Bir siparişin durum sorgulamaları ve iadeleri her zaman, ödemesinin oluşturulduğu modun anahtarını kullanır. Varsayılan: açık.

Test secret key: Pagar.me test gizli anahtarı (sk_test_...). Test modu açık olduğunda kullanılır.

Live secret key: Pagar.me canlı gizli anahtarı (sk_...). Test modu kapalı olduğunda kullanılır. Gizli tutun.

Sürüm 1.0'daki tek gizli anahtar otomatik olarak taşınır: test anahtarı Test secret key alanına aktarılır ve test modu açılır; aksi halde canlı anahtar olarak kalır ve test modu kapatılır.

Ödeme sayfası

Payment methods: Pagar.me ödeme sayfasında sunulan yöntemler. Yalnızca Pagar.me hesabınızda etkinleştirilmiş yöntemleri seçin. Varsayılan: Credit card, PIX ve Boleto.

Boleto due in (days): boleto'nun vadesine kalan gün sayısı, 1 ile 30 arasında. Pagar.me ödemeyi onaylayana kadar sipariş On hold durumunda kalır. Varsayılan: 3.

Ödeme bildirimleri (webhook)

Pagar.me panelinde Settings > Webhooks bölümünü açın ve bu bölümde gösterilen URL ile bir webhook oluşturun. Görünümü şöyledir: https://your-site/wc-api/webhook_wc_pagarme/. Ayarların gösterdiği biçimde birebir kopyalayın.

Şu olayları seçin:

Webhook'un parolaya veya imzaya ihtiyacı yoktur. İçeriği hiçbir zaman güvenilir kabul edilmez: mağaza ondan yalnızca Pagar.me sipariş kimliğini alır ve bu siparişi, oluşturulduğu modun anahtarıyla Pagar.me API'sinden okur. Aynı Pagar.me hesabındaki diğer mağazaların siparişlerine ait bildirimler yok sayılır. Webhook olmadan, daha sonra yapılan PIX ve boleto ödemeleri yalnızca müşteri mağazaya döndüğünde onaylanır.

Gelişmiş

Debug log: Log API requests and notifications, ayrıntıları WooCommerce > Status > Logs altına, kaynak wcp_pagarme_gateway olarak yazar. Hatalar her zaman kaydedilir. Günlükler anahtar 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

Müşteri ödeme yöntemini seçer (varsayılan olarak Pagar.me) ve siparişi verir. Geçerli bir fatura e-posta adresi gereklidir. Eklenti, sipariş toplamı için BRL cinsinden bir Pagar.me siparişi oluşturur; sipariş kalemleri, kargo ve ücretlerle birlikte (kalemler tam olarak toplanamıyorsa, sipariş numarasını içeren tek bir Order # satırıyla) ve müşteriyi Pagar.me ödeme sayfasına gönderir. Müşterinin adı, e-posta adresi ve Brezilya için telefon numarası ile fatura adresi Pagar.me'ye iletilir. CPF veya CNPJ, varsa Brazilian Market on WooCommerce eklentisinin alanlarından alınır; yoksa müşteri bunu Pagar.me sayfasında girer.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Pagar.me onayladıktan sonra ödenmiş olarak işaretlenir: mağaza Pagar.me siparişini API'den okur ve ödenen tutar ile para biriminin siparişle eşleşmesi gerekir. Yapılan bir kart, PIX veya boleto ödemesi siparişi ödenmiş olarak işaretler. Düzenlenmiş ama henüz ödenmemiş bir PIX veya boleto, Pagar.me ödemeyi webhook ile onaylayana kadar siparişi On hold durumuna getirir.

Müşteri ödeme yapmadan dönerse veya ödeme reddedilmiş ya da iptal edilmişse, Pay for order sayfasına gider ve The Pagar.me payment was not completed. You can pay the order below. veya The Pagar.me payment was declined or canceled. You can try again below. mesajını görür.

Müşteri yeniden ödeme yaptığında, açık olan Pagar.me ödeme sayfası tutar ve mod aynıysa yeniden kullanılır; aksi halde yenisi oluşturulmadan önce Pagar.me'de kapatılır. Önceki deneme bu arada ödendiyse veya PIX ya da boleto'su hâlâ bekliyorsa, sipariş yeni bir ödeme olmadan güncellenir. Önceki sayfa kapatılamazsa siparişle eşleşmiş kalır; böylece o sayfada yapılan bir ödeme yine kaydedilir.

Pagar.me ödemeyi başlatamazsa, müşteri kısa bir mesaj görür, örneğin Could not connect to Pagar.me. Please try again in a moment. veya geçersiz fatura bilgileriyle ilgili Pagar.me mesajı. Teknik 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 ödeme sayfanızda kart formu, kayıtlı kart, abonelik veya yinelenen ödeme özelliği, taksit kuralı, bölünmüş ödeme (pazar yeri), yalnızca provizyonlu kart ödemesi ve Pagar.me Hub entegrasyonu yoktur.

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri Pagar.me'ye yönlendirildi ve henüz ödeme yapmadı ya da bir PIX veya boleto oluşturmadı. Bir not Pagar.me sipariş kimliğini ve modu gösterir.

Processing: ödeme onaylandı. Bu, ödemeden sonra WooCommerce'in standart durumudur; yalnızca sanal, indirilebilir ürün içeren siparişler Completed olur. Sipariş notu Pagar.me sipariş kimliğini ve ödeme yöntemini gösterir. İşlem kimliği Pagar.me sipariş kimliğidir (or_...).

On hold: bir PIX veya boleto düzenlenmiştir (ya da bir kart ödemesi incelemededir) ve ödeme beklemektedir; veya boleto yalnızca kısmen ödenmiştir; veya ödenen tutar ya da para birimi siparişten farklıdır; veya sipariş iptal edildikten sonra bir ödeme gelmiştir; veya müşteri ödeme yöntemini değiştirdikten sonra sipariş Pagar.me'de ödenmiştir; veya ödenmiş bir siparişte chargeback açılmıştır. Sipariş notu nedenini açıklar. Siparişi inceleyin ve Processing olarak ayarlayın ya da ödemeyi Pagar.me'de iade edin.

Failed: ödeme başarısız oldu veya Pagar.me siparişi iptal edildi ya da süresi doldu (örneğin ödenmemiş bir boleto). Ödenmemiş bir siparişi Failed yapabilecek yalnızca son denemedir. Müşteri yeniden ödeme yapabilir.

Refunded: ödeme Pagar.me'de iade edildi veya iptal edildi.

Her Pagar.me durumu bir kez uygulanır; bu nedenle tekrarlanan webhook'lar veya dönüşler not, e-posta ya da stok düşümü eklemez. Ödenmiş bir sipariş asla yeniden beklemeye veya başarısız duruma alınmaz; iptal edilmiş veya iade edilmiş bir sipariş asla yeniden açılmaz. Aynı WooCommerce siparişinin ikinci bir Pagar.me siparişi ödenirse, bir not Pagar.me panelinde kopyayı iade etmenizi ister.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Pagar.me düğmesine tıklayın (düğmede ödeme yönteminizin başlığı görünür). Kart ve PIX ödemelerinde tam ve kısmi iadeler, Pagar.me'de hâlâ iade edilebilir tutar kadar desteklenir. İade, ödemenin yapıldığı modun anahtarıyla gönderilir. İade yalnızca Pagar.me onayladığında kaydedilir; aksi halde WooCommerce hatayı gösterir, örneğin Pagar.me refused the refund: ... veya Pagar.me did not confirm the refund, ve hiçbir iade kaydedilmez. Başarılı bir iade, tahsilat kimliğiyle birlikte sipariş notlarına eklenir.

Boleto ödemeleri yalnızca müşterinin banka hesabına iade edilebilir. Bunları Pagar.me panelinde iade edin, ardından iadeyi Refund via Pagar.me kullanmadan WooCommerce'e elle kaydedin.

Pagar.me panelinde yapılan tam iade veya iptal webhook ile gelir ve siparişi Refunded olarak ayarlar. Bir chargeback sipariş notu ekler ve Processing veya Completed durumundaki bir siparişi On hold durumuna alır.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Payments > Pagar.me sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blok durumu gösterir; örneğin lisansın hangi tarihe kadar etkin olduğunu 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 sitenin alan adı hakkını serbest bırakmaz. Alan adı hakkını vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan Pagar.me, ö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. Oturum açmış mağaza yöneticileri ödeme yöntemini (unlicensed — visible to admins only) işaretiyle görmeye devam eder; 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 onaylanmaya devam eder ve iadeler çalışır.

Lisans 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

Ödeme sayfasında Pagar.me görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu, geçerli modun gizli anahtarının girildiğini (test modunda Test secret key, canlı modda Live secret key) ve mağaza para biriminin BRL olduğunu kontrol edin. Ayarlar sayfası her durumda bir uyarı gösterir.

Ödeme yapıldı ama sipariş Pending payment veya On hold durumunda kaldı: webhook çalışmıyor. Pagar.me panelinde, kullandığınız hesap ve mod için webhook'un var olduğunu, URL'sinin ayarlarda gösterilenle birebir aynı olduğunu ve yukarıda listelenen olayların seçili olduğunu kontrol edin. Sipariş, müşteri mağazaya döndüğünde de kontrol edilir.

Webhook verification failed, retry later yanıtı veriyor: mağaza Pagar.me siparişini API'den okuyamadı; örneğin o modun anahtarı eksik olabilir veya API yanıt vermemiş olabilir. Pagar.me webhook'u yeniden dener.

Webhook busy, retry later yanıtı veriyor: sipariş aynı anda başka bir istek tarafından güncelleniyordu. Pagar.me webhook'u yeniden dener.

Webhook unknown order yanıtı veriyor: Pagar.me siparişi bu mağaza tarafından oluşturulmamış; örneğin aynı hesaptaki başka bir mağazanın siparişi. Hiçbir şey değiştirilmez.

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

Müşteri Pagar.me payments are not available right now mesajını görüyor: gizli anahtar yanlış veya eksik. Geçerli modun anahtarını kontrol edin.

Müşteri Pagar.me could not start the payment mesajını görüyor: Pagar.me fatura bilgilerini reddetti. Mesaj sorunu belirtir; tam neden sipariş notlarındadır.

Müşteri Pagar.me only supports payments in Brazilian Real (BRL) mesajını görüyor: sipariş başka bir para biriminde; örneğin bir para birimi değiştirme eklentisi nedeniyle.

Ödemeden sonra sipariş On hold: sipariş notunu okuyun. Bir PIX veya boleto ödeme bekliyor, ödenen tutar ya da para birimi farklıydı veya ödeme sipariş iptal edildikten sonra geldi.

Boleto için iade başarısız oluyor: boleto ödemeleri API üzerinden iade edilemez. Pagar.me panelinde iade edin ve iadeyi elle kaydedin.

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

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Kaldırmak için Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ağ geçidi ayarları ve eklentinin günlükleri yalnızca Delete data on uninstall açıksa kaldırılır. Aksi halde sonraki bir yeniden kurulum için saklanır. Mevcut siparişler ödeme notlarını, işlem kimliklerini ve Pagar.me verilerini korur.

Pagar.me, ilgili sahibinin ticari markasıdır. Bu eklenti Pagar.me ile bağlantılı değildir ve Pagar.me tarafından onaylanmamıştır.