VibeFox Vindi for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x.

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

Mağaza para birimi: Brezilya Reali (BRL). Vindi yalnızca BRL ile tahsilat yapar, bu yüzden ödeme yöntemi başka bir para birimindeki sepetler için gizlenir.

Vindi hesabı: Vindi hesabınızın API anahtarına ihtiyacınız vardır. Vindi sandbox, kendi anahtarına sahip ayrı bir Vindi test hesabıdır. Boleto, PIX ve BolePix'i sunmak istiyorsanız bunların Vindi hesabınızda da etkin olması gerekir.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek bir alan adında çalışır.

Kurulum

1. Yönetim panelinde 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 Vindi Gateway modülünü bulup Configure düğmesine tıklayın.

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

4. Sandbox API key alanına yapıştırın ve hazır olduğunuzda Live API key alanına da yapıştırın. Offered methods seçeneklerini belirleyin.

5. Ayarlardaki webhook URL'sini kopyalayıp Vindi'ye ekleyin (bkz. Yapılandırma).

6. Enable / Disable seçeneğini açın ve Save düğmesine tıklayın. Sandbox modunda bir ödeme deneyin, ardından gerçek ödemeleri kabul etmek için Sandbox mode seçeneğini kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Vindi payment ve Vindi 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ünden sınırlayabilirsiniz; modülün orada BRL için izinli olması gerekir.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme sayfanın tamamını kaydeder. Alanların üstünde sayfa, mağaza para birimi BRL değilse ya da geçerli modun API anahtarı boşsa sizi uyarır. Her iki durumda da ödeme yöntemi ödeme sayfasında gösterilmez. Kaydedildiğinde anahtarların baş ve son boşlukları temizlenir. Hiçbir ödeme yöntemi seçilmemişse kredi kartı seçilir ve sayfa Choose at least one payment method — credit card was selected. mesajını gösterir. Boş bir Title kaydedilmez: sayfa Enter a title for the payment method. mesajını gösterir.

Vindi

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

Title: ödeme sayfasında gösterilen ödeme yönteminin adı. Siparişe kaydedilen ödeme yöntemi adı da budur. Varsayılan: Vindi. Zorunlu.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay by credit card on the secure Vindi page, or by boleto / PIX.

API anahtarları

Anahtarları Vindi panelinde Settings > API keys altında oluşturun: canlı ortam için app.vindi.com.br üzerinde, sandbox için sandbox-app.vindi.com.br üzerinde. Canlı ortam ve sandbox ayrı adreslere ve anahtarlara sahiptir. Her ödeme faturasının oluşturulduğu ortamı kaydeder; bu yüzden kontroller, iptaller ve iadeler her zaman o ortamı kullanır.

Sandbox mode: yeni ödemeleri Vindi sandbox'ta oluşturur; sandbox-app.vindi.com.br adresini ve sandbox API anahtarını kullanır. Müşteriler ödeme sayfasında TEST MODE notunu görür: Vindi sandbox: no real charges. Varsayılan: açık. Gerçek ödemeleri kabul etmek için kapatın.

Live API key: canlı Vindi hesabının özel anahtarı. Yalnızca Vindi API'sine gönderilir.

Sandbox API key: Vindi sandbox hesabının özel anahtarı.

Kayıtlı anahtarlar bir daha 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.

Clear saved keys: bir anahtarı işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödeme yöntemleri

Offered methods: müşterilerin seçebileceği yöntemler. Varsayılan: kredi kartı. Yöntemlerin Vindi hesabınızda da etkin olması gerekir.

Boleto, PIX ve BolePix için ödeme sayfasında istenen müşterinin CPF veya CNPJ bilgisi gerekir.

Ödeme bildirimleri (webhook)

Webhook, bir faturanın ödendiğini, iptal edildiğini, reddedildiğini veya iade edildiğini mağazanıza bildirir. Bu bölümdeki Webhook URL alanı URL'yi gösterir. Dostça URL'lerle şöyle görünür: https://your-shop/module/wcp_vindi_gateway/webhook?token=... ve modül tarafından oluşturulan gizli bir jeton içerir. Ayarların gösterdiği şekliyle birebir kopyalayın. Vindi'de Settings > Webhooks bölümüne gidin; hem canlı hesapta hem sandbox hesabında bu URL'yi ekleyin ve şu olayları seçin:

Vindi bildirimlerini imzalamaz; bu yüzden jetonu eksik veya yanlış olan istekler reddedilir ve her bildirim, bir sipariş değişmeden önce modülün faturayı yalnızca Vindi API'si üzerinden yeniden okumasını sağlar. Webhook olmadan, kartla yapılan bir ödeme ancak müşteri aynı sepetle siparişi yeniden verdiğinde algılanır (ödenmiş fatura bulunur ve sipariş oluşturulur); boleto veya PIX ödemesi ise müşteri sipariş onay sayfasını yeniden açtığında algılanır.

Gelişmiş

Debug log: API çağrılarını ve bildirimleri modül klasöründeki logs/wc_vdi_debug.log.php dosyasına kaydeder. Dosya web üzerinden açılamaz. Hatalar ve uyarılar kapalı olsa bile her zaman kaydedilir. Anahtarlar, webhook jetonu ve müşteri verileri hiçbir zaman kaydedilmez. Varsayılan: kapalı.

Log: günlüğün boyutunu ve son girişlerini gösterir. Temizlemek için Clear log düğmesine tıklayın.

Delete data on uninstall: açıksa modül kaldırıldığında ayarlar, webhook jetonu ve günlükler silinir. Siparişler ve siparişlerin Vindi fatura referansları korunur. Varsayılan: kapalı.

Ödeme sayfası

Müşteri ödeme yöntemini seçer (varsayılan olarak Vindi). Birden fazla yöntem sunulduğunda ödeme kutusunda Pay with ve kredi kartı, boleto, PIX veya BolePix arasından seçim görünür. Boleto, PIX veya BolePix sunulduğunda kutuda ayrıca bir CPF or CNPJ alanı bulunur. Kredi kartı sunulmuyorsa bu alan zorunludur; aksi halde Required for boleto and PIX. yazar. Fatura adresindeki Identification number veya VAT numarası geçerli bir CPF ya da CNPJ içeriyorsa alan bunlardan doldurulur. Numara kontrol basamaklarıyla doğrulanır. Eksik bir şey varsa müşteri Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. veya Please enter your CPF or CNPJ — it is required for boleto and PIX. mesajını görür.

Müşteri siparişi onayladığında modül, bu sepet için fatura adresinden bir Vindi müşterisi ve sepet tutarı için tek taksitli bir Vindi faturası oluşturur. Vindi'de fatura Order # adıyla ve sepet numarasıyla kaydedilir.

Kredi kartı: müşteri Vindi fatura sayfasına yönlendirilir ve orada öder. Bu aşamada henüz sipariş yoktur. Vindi'nin faturalar için bir dönüş URL'si yoktur; bu yüzden müşteri otomatik olarak mağazaya geri döndürülmez. Sipariş, Vindi ödemeyi webhook ile onayladığında oluşturulur. Müşteri aynı sepetle siparişi yeniden verirse bekleyen fatura yeniden sunulur veya fatura zaten ödenmişse sipariş hemen oluşturulur.

Boleto, PIX ve BolePix: fatura hemen düzenlenir, sipariş Awaiting Vindi payment durumuyla oluşturulur ve müşteri sipariş onay sayfasına gelir. Orada ve müşteri hesabındaki sipariş ayrıntılarında bir Payment bölümü PIX QR kodunu, Copy code düğmeli kopyala-yapıştır PIX kodunu ve son kullanma tarihini, ayrıca bir Open boleto düğmesini gösterir. Sipariş onay e-postası PIX kodunu ve boleto bağlantısını içerir. Vindi boleto veya PIX verilerini döndürmezse fatura iptal edilir ve müşteri bir hata görür.

Sipariş, Vindi onaylamadan ödenmiş olarak işaretlenmez: modül faturayı Vindi API'sinden okur; para birimini, faturanın sepete ait olduğunu (sepet kodu ve Vindi müşterisi) ve ödenen tutarın sipariş toplamına eşit olduğunu kontrol eder. Sipariş onay sayfası, bekleyen bir siparişi API üzerinden en fazla 15 saniyede bir yeniden kontrol eder. Ödeme alındığında Your payment with Vindi has been received. mesajını gösterir. Fatura Vindi'de incelenirken We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. mesajını gösterir. İptal edilmiş bir sipariş için This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid. mesajını gösterir.

Aynı sepet için yeni bir ödeme denemesi, yöntem, tutar ve ortam aynıysa bekleyen Vindi faturasını yeniden kullanır. Aksi halde yeni bir fatura oluşturulmadan önce önceki fatura Vindi'de iptal edilir; böylece müşteri aynı sepeti iki kez ödeyemez. Önceki fatura bu arada ödendiyse sipariş oluşturulur ve yeni fatura düzenlenmez.

Vindi ödemeyi başlatamazsa müşteri ödeme sayfasında kısa bir mesajla kalır; örneğin CPF / CNPJ, fatura adresi (boleto için cadde, posta kodu, şehir ve eyalet zorunludur), e-posta veya telefon numarasını kontrol etmesi ya da Vindi'nin geçici olarak kullanılamadığı bildirilir. Teknik neden günlüğe yazılır.

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

Modül yalnızca tek taksitli tek seferlik ödemeleri kabul eder. Abonelik veya yinelenen faturalandırma, kayıtlı kart, taksit ve sitenizde kart formu yoktur: kart her zaman Vindi sayfasında girilir.

Siparişler ve iadeler

Sipariş durumları

No order yet: bir kartla ödeme başlatıldı ve Vindi henüz onaylamadı. Yalnızca sepet vardır.

Awaiting Vindi payment: boleto, PIX veya BolePix ödemesi bekleniyor (not Awaiting ... payment at Vindi.). Vindi faturanın ödendiğini bildirdiğinde sipariş Payment accepted durumuna geçer.

Payment accepted: ödeme onaylandı. Ödeme, işlem kimliği olarak Vindi fatura kimliğiyle kaydedilir ve bir not Vindi faturasını, tutarı ve ortamı gösterir.

Vindi payment on hold: Vindi faturası incelemede, ödenmiş fatura siparişle eşleşmiyor (para birimi, tutar, sepet kodu veya Vindi müşterisi) ya da fatura, sipariş iptal edildikten sonra ödenmiş. Not nedenini açıklar ve siparişe ödenen bir tutar kaydedilir. Siparişi ve stoku kontrol edin, ardından siparişi tamamlayın veya ödemeyi iade edin.

Payment error: Vindi, bekleyen bir siparişin ödeme denemesini reddetti. Varsa not, ödeme kuruluşunun nedenini gösterir. Müşteri aynı faturayı yine ödeyebilir ve sonraki bir ödeme siparişi Payment accepted durumuna taşır.

Canceled: bekleyen bir siparişin faturası Vindi'de iptal edildi. Mağazada bir siparişi iptal ettiğinizde, bekleyen Vindi faturası da iptal edilir ve artık ödenemez. Bu mümkün değilse bir not, faturayı Vindi panelinde iptal etmenizi ister.

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

Zaten ödenmiş bir sipariş için ikinci bir fatura ödenirse sipariş değişmez. Bir not, Vindi'de bir ödemeyi iade etmenizi ister.

Vindi ödeme bloğu

Sipariş sayfasında Vindi faturası ve tahsilatı, ortam (sandbox ödemeleri için Sandbox rozetiyle), ödeme yöntemi, durum, ödenen ve iade edilen tutar, iade geçmişi, tüm Bills of this cart kayıtları ve siparişin Vindi notes notlarını içeren bir Vindi payment bloğu gösterilir.

İadeler

Vindi payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Vindi düğmesine tıklayın. Refund this amount through Vindi? This cannot be undone. sorusunu onaylayın. Kart ve PIX ödemelerinin tam ve kısmi iadeleri desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modül sayfalarına erişim gerekmez. İadeler, Vindi'nin fiilen tahsil ettiği tutarla sınırlıdır; bu yüzden bir uyuşmazlıktan sonra sipariş toplamına değil, müşterinin ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin ortamında (canlı veya sandbox) gönderilir; bu yüzden o ortamın API anahtarı ayarlanmış olmalıdır. Tam iade ayrıca Vindi'deki faturayı iptal eder ve siparişi Refunded durumuna getirir; kısmi iade durumu değiştirmez. Başarılı bir iade, Vindi tahsilatı ve durumuyla birlikte iade geçmişine ve notlara eklenir. Vindi veya ödeme kuruluşu iadeyi reddederse blok hatayı gösterir ve hiçbir iade kaydedilmez. İadeler, Vindi faturayı ödenmiş olarak bildirdikten sonra kullanılabilir.

Vindi boleto ödemelerini iade edemez. Blok Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually. mesajını gösterir.

Modül kredi notu (credit slip) oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Vindi üzerinden para göndermez. Vindi panelinde yapılan iadeler charge_refunded webhook'u ile gelir ve notlara eklenir. Sipariş durumu otomatik değişmez; gerekirse bunları PrestaShop'ta manuel iadeyle kaydedin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınmış bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Vindi Gateway lisans bloğu, Modules > Module Manager > VibeFox Vindi Gateway > Configure sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blokta anahtar maskelenmiş olarak, durum (örneğin lisansın geçerli olduğu son tarih ve alan adınız) ve şu düğmeler görünür: 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. Bunların altında Product: presta-payment-vindi satırı ve hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure izni olan çalışanlar değiştirebilir. Bloktaki metinler 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 License expired on ve bir tarih. 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, bilinen son 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. 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 Vindi, ödeme adımı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 back office'e giriş yaptığınızı bilmez; bu nedenle ödeme yöntemi sizin için de gizlenir: modülü anahtar satın almadan önce kurabilirsiniz, ama ödeme adımında test edemezsiniz. Modules > Module Manager sayfasında Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten oluşturulmuş faturalar Vindi webhook'u ile onaylanmaya devam eder ve iadeler çalışır.

Bir lisansın süresi dolduğunda 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, sonrasında haftada bir. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

Vindi ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu, sepet para biriminin BRL olduğunu, Offered methods altında en az bir yöntemin seçili olduğunu ve geçerli modun bir API anahtarı bulunduğunu kontrol edin: sandbox modunda Sandbox API key, canlı modda Live API key. Anahtar eksikse ya da para birimi BRL değilse ayarlar sayfası bir 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ı ya da sipariş hâlâ Awaiting Vindi payment durumunda: webhook çalışmıyor. Vindi'de kullandığınız hesapta (canlı veya sandbox) webhook'un var olduğunu, URL'sinin ayarlarda gösterilenle, jeton dahil, birebir aynı olduğunu ve dört olayın da seçili olduğunu kontrol edin.

Webhook Forbidden yanıtı veriyor: URL'deki jeton eksik ya da yanlış. URL'yi ayarlardan yeniden kopyalayın.

Webhook Verification failed, retry later yanıtı veriyor: fatura Vindi API'sinden okunamadı (örneğin o ortamın API anahtarı kaldırılmış), sepet aynı anda başka bir istek tarafından güncelleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Vindi bildirimi yeniden gönderir. Günlük nedeni gösterir.

Tarayıcıda webhook URL'si Method not allowed gösteriyor: bu normaldir. URL yalnızca Vindi'den gelen istekleri kabul eder.

Müşteri This payment method is temporarily unavailable mesajını görüyor: Vindi API anahtarını reddetti. Geçerli modun anahtarını kontrol edin.

Müşteri sipariş verirken bir hata görüyor: modül sayfasındaki Log alanına bakın. Hatalar, Debug log kapalıyken bile kaydedilir. Boleto için fatura adresinde cadde, posta kodu, şehir ve eyalet bulunmalıdır.

Sipariş Vindi payment on hold durumunda: Vindi payment bloğundaki notları okuyun (bkz. Sipariş durumları), ardından siparişi tamamlayın veya ödemeyi iade edin.

Canlıya geçtikten sonra eski sandbox siparişleri: her ödeme, faturasının ortamını korur. Sandbox siparişlerinin kontrolleri, iptalleri ve iadeleri, sandbox anahtarı ayarlarda kaldığı sürece bu anahtarı kullanmaya devam eder.

İade başarısız oluyor: mesajı okuyun. Boleto ödemeleri Vindi üzerinden iade edilemez ve ödemenin ortamının API anahtarı ayarlanmış olmalıdır.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Vindi 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 ayarlar, webhook jetonu ve günlükler silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Siparişlerin Vindi faturaları ve iadeleri ile Awaiting Vindi payment ve Vindi payment on hold sipariş durumları her zaman korunur; böylece daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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