VibeFox Pagar.me for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

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

Para birimi: Brezilya reali (BRL). Ödeme yöntemi, başka bir para biriminde olan sepetler için gizlenir.

Pagar.me hesabı: Pagar.me hesabınızın gizli anahtarlarına ihtiyacınız var: 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. 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 Pagar.me 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. Test gizli anahtarını girin; canlıya geçtiğinizde canlı gizli anahtarı girin.

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

6. Enable / Disable seçeneğini açın ve Save düğmesine tıklayın. Test 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 Pagar.me payment ve Pagar.me payment on hold. PrestaShop, tüm para birimleri, ülkeler ve müşteri grupları için yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünde sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Pagar.me 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: 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ğazanın varsayılan para birimi BRL değilse uyarır.

Pagar.me

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

Title: müşterinin ödeme sayfasında gördüğü ödeme yöntemi adı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Pagar.me. Zorunlu.

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 gerçek mi olduğunu anahtar belirler.

Test mode: test gizli anahtarını kullanır, gerçek tahsilat yapılmaz. Açık olduğu sürece müşteriler ödeme yönteminin altında TEST MODE — Use test credentials. No real charges. ifadesini görür. 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.

Kaydedilmiş 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 secret keys: bir anahtarı işaretleyip Save düğmesine tıklayarak kaldırın. Boş alan kayıtlı değeri korur.

Ö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. Hiçbiri işaretli değilse varsayılan yöntemler kullanılır. Varsayılan: Credit card, PIX and Boleto.

Boleto due in (days): boleto'nun vadesine kalan gün sayısı, 1 ila 30. Pagar.me ödemeyi onaylayana kadar sipariş Awaiting Pagar.me payment durumunda kalır. Varsayılan: 3. Başka bir değer kaydetme sırasında Boleto due in (days): enter a number from 1 to 30. mesajıyla reddedilir.

Ödeme bildirimleri (webhook)

Pagar.me panelinde Settings > Webhooks bölümünü açın ve bu bölümde Webhook URL altında gösterilen URL ile bir webhook oluşturun. Dostça URL'lerle şu biçimde görünür: https://your-shop/module/wcp_pagarme_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. Ayarların gösterdiği şekliyle birebir kopyalayın.

Bu olayları seçin (bu bölümde de listelenmişlerdir):

Webhook için parola veya imza gerekmez. İçeriğine hiçbir zaman güvenilmez: mağaza ondan yalnızca Pagar.me sipariş kimliğini alır ve 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: API isteklerini ve bildirimleri modül klasöründeki logs/wc_pgm_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar her zaman kaydedilir. Anahtarlar ve müşteri verileri kaydedilmez. Varsayılan: kapalı.

Log: kaydın boyutunu ve en son girişlerini gösterir. Temizlemek 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 kayıt silinir. Siparişler, Pagar.me ödeme verileri (iadeler için gerekli) ve sipariş durumları korunur. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Pagar.me) ve onaylar. Geçerli bir e-posta adresi gerekir. Modül, BRL cinsinden sepet tutarı için sepet satırları, kargo ve hediye paketi ile bir Pagar.me siparişi oluşturur (sepette indirim varsa sepet numarası içeren tek bir Order # satırı ile) ve müşteriyi Pagar.me ödeme sayfasına gönderir. Bu aşamada mağazanızda henüz bir sipariş yoktur.

Müşterinin adı ve e-posta adresi Pagar.me'ye iletilir. CPF veya CNPJ, adresin Identification number alanından ya da VAT number alanından alınır; ayrıca bir Brezilya cep telefonu numarası da iletilir. Fatura adresi yalnızca 8 haneli CEP ve eyalet bilgisi içeren bir Brezilya adresi için iletilir. PrestaShop varsayılan olarak Brezilya eyaletlerini içermez, bu nedenle müşteri genellikle adresi Pagar.me sayfasında girer. CPF veya CNPJ yoksa müşteri bunu da orada 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 birimi sepetle eşleşmelidir. Başarılı bir kart, PIX veya boleto ödemesi siparişi Payment accepted durumunda oluşturur ve müşteri Your payment with Pagar.me has been received. ifadesinin yer aldığı standart sipariş onay sayfasını görür. Düzenlenmiş ancak henüz ödenmemiş bir PIX veya boleto siparişi Awaiting Pagar.me payment durumunda oluşturur ve sayfa Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. mesajını gösterir. Sonraki her dönüşte Pagar.me siparişi yeniden okunur; bu nedenle webhook ulaşmamış olsa bile bu sırada ödenen bir PIX veya boleto uygulanır. Bu tür bir siparişin ödemesi başarısız olduysa veya süresi dolduysa sayfa Your Pagar.me payment was not completed. Please contact us about this order. mesajını gösterir.

Müşteri ödeme yapmadan geri dönerse ödeme sayfasına The Pagar.me payment was not completed. You can pay the order below. mesajıyla yönlendirilir. Ödeme reddedilmiş veya iptal edilmişse mesaj The Pagar.me payment was declined or canceled. You can try again below. olur. Sepet korunur. Sipariş zaten varsa ve ödemesi başarısız olmuş veya süresi dolmuşsa mesaj The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. olur. Pagar.me'ye ulaşılamazsa, müşteriden tekrar ödeme yapmamasını isteyen ve Check again ile Back to checkout seçeneklerini sunan bir Payment confirmation sayfası açılı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 ödenmişse veya PIX ya da boleto'su hâlâ bekliyorsa, sipariş yeni bir ödeme olmadan oluşturulur. Önceki sayfa kapatılamazsa sepetle eşleşmeye devam eder; bu nedenle o sayfada yapılan bir ödeme yine kaydedilir.

Pagar.me ödemeyi başlatamazsa müşteri ödeme sayfasında kalır ve Could not connect to Pagar.me. Please try again in a moment. gibi kısa bir mesaj ya da geçersiz fatura bilgileriyle ilgili Pagar.me mesajı görür. Teknik neden kayda yazılır.

Webhook, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasından etkilenmez.

Modülün ödeme sayfanızda kart formu, kayıtlı kart, abonelik veya yinelenen ödeme özelliği, taksit kuralı, bölünmüş ödeme (pazaryeri), yalnızca provizyonlu kart ödemesi ve Pagar.me Hub entegrasyonu yoktur.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri Pagar.me'ye yönlendirildi ve henüz ödeme yapmadı ya da PIX veya boleto düzenlenmedi. Yalnızca sepet var.

Payment accepted: ödeme onaylandı. Ödeme, işlem kimliği olarak Pagar.me sipariş kimliği (or_...) ile kaydedilir ve bir not Pagar.me siparişini ve ödeme yöntemini gösterir.

Awaiting Pagar.me payment: bir PIX veya boleto düzenlendi (ya da bir kart ödemesi incelemede) ve ödeme bekliyor. Pagar.me ödemeyi onayladığında sipariş Payment accepted durumuna geçer.

Pagar.me payment on hold: boleto yalnızca kısmen ödendi; ya da ödenen tutar veya para birimi siparişten farklı (örneğin ödeme başladıktan sonra sepet değiştirildi); ya da ödeme sipariş iptal edildikten sonra geldi; ya da ödenmiş bir siparişte chargeback açıldı. Not nedenini açıklar. Siparişi kontrol edin ve yerine getirin ya da ödemeyi iade edin.

Payment error: beklemedeki veya bekletilen bir siparişin ödemesi başarısız oldu ya da Pagar.me siparişi iptal edildi veya süresi doldu (örneğin ödenmemiş bir boleto). Pagar.me daha sonra bir ödeme bildirirse sipariş yine de Payment accepted durumuna geçer.

Refunded: ödeme modül aracılığıyla tamamen iade edildi ya da Pagar.me'de iade edildi veya iptal edildi.

Her Pagar.me durumu yalnızca bir kez uygulanır; bu nedenle tekrarlanan webhook'lar veya dönüşler not ya da ödeme eklemez. Aynı sepetin ikinci bir Pagar.me siparişi ödenirse, bir not sizden kopyayı Pagar.me panelinden iade etmenizi ister.

Pagar.me ödeme bloğu

Sipariş sayfasında Pagar.me sipariş kimliği ve tahsilat kimlikleri, ödeme yöntemi, durum, ödenen ve iade edilen tutar, test ödemeleri için bir Test mode rozeti, iade geçmişi ve siparişin Pagar.me notes bölümünü içeren bir Pagar.me payment bloğu gösterilir.

İadeler

Pagar.me payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isterseniz bir neden yazın ve Refund via Pagar.me düğmesine tıklayın. Refund this amount through Pagar.me? This cannot be undone. sorusunu onaylayın. Kart ve PIX ödemelerinde tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir. Pagar.me'nin fiilen tahsil ettiği tutara kadar iade yapabilirsiniz; bu nedenle bir tutar uyuşmazlığından sonra sınır sipariş toplamı değil, müşterinin ödediği tutardır. İade, ödemenin yapıldığı modun anahtarıyla gönderilir; bu yüzden o modun gizli anahtarının girilmiş olması gerekir. İade yalnızca Pagar.me onayladığında kaydedilir. Aksi halde blok 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, iade geçmişine ve notlara tahsilat kimliğiyle birlikte eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. İadeler, Pagar.me ödemeyi bildirdikten sonra kullanılabilir.

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

Modül kredi notu (credit slip) oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Pagar.me üzerinden para göndermez.

Pagar.me panelinde yapılan tam iade veya iptal webhook ile gelir, siparişi Refunded durumuna getirir ve bir not ekler. Bir chargeback bir not ekler ve ödenmiş bir siparişi Pagar.me payment on hold durumuna alır.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Modules > Module Manager > VibeFox Pagar.me Gateway > Configure sayfasında, ayarların üstündeki ilk blok lisans bloğudur: License — VibeFox Pagar.me 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-pagarme 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 Pagar.me, ödeme sayfasında 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 sayfasında 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

Pagar.me ödeme sayfasında 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 sepet para biriminin BRL olduğunu kontrol edin. Anahtar eksikse ayarlar sayfası bir 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.

Ödeme yapıldı ama sipariş oluşturulmadı ya da sipariş Awaiting Pagar.me payment durumunda kaldı: webhook çalışmıyor. Pagar.me panelinde, kullandığınız hesap ve mod için webhook'un var olduğunu, URL'sinin Webhook URL altında gösterilenle tam olarak aynı olduğunu ve yukarıda listelenen olayların seçili olduğunu kontrol edin. Sipariş ayrıca müşteri mağazaya her 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 olduğu ya da API yanıt vermediği için. Pagar.me webhook'u yeniden dener.

Webhook busy yanıtı veriyor: sepet aynı anda başka bir istek tarafından güncelleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Pagar.me webhook'u yeniden dener. Nedenini görmek için Debug log seçeneğini açın.

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 Pagar.me payments are not available right now mesajını görüyor: gizli anahtar yanlış ya da 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; örneğin adresin Identification number alanındaki CPF. Mesaj sorunu belirtir; tam neden kayıttadır.

Müşteri Pagar.me only supports payments in Brazilian Real (BRL) mesajını görüyor: sepet başka bir para biriminde.

Müşteri This order already has a Pagar.me payment that the store has to review mesajını görüyor: sepetin daha önceki bir ödemesinin sizin incelemenize ihtiyacı var. Pagar.me panelini ve kaydı kontrol edin.

Ödemeden sonra sipariş Pagar.me payment on hold durumunda: Pagar.me payment bloğundaki notları okuyun (bkz. Sipariş durumları), ardından siparişi yerine getirin ya da ödemeyi iade edin.

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

İade, mod ile ilgili bir mesajla başarısız oluyor: ödeme test veya canlı modda yapıldı ve o modun gizli anahtarı girilmemiş. Anahtarı girin ve yeniden deneyin.

Geliştiriciler, Pagar.me sipariş verilerini gönderilmeden önce actionWcpPagarmeOrderData kancasıyla değiştirebilir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Pagar.me 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 kayıt silinir. Kapalıysa, sonraki yeniden kurulum için tüm ayarlar korunur. Siparişlerin Pagar.me ödeme verileri ile Awaiting Pagar.me payment ve Pagar.me payment on hold sipariş durumları her zaman korunur; bu sayede daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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