VibeFox Iugu 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). Iugu yalnızca BRL ile tahsilat yapar. Ödeme yöntemi, başka para birimindeki sepetler ve R$ 1,00'ın altındaki toplamlar (Iugu'nun asgari tutarı) için gizlenir.

Iugu hesabı: Iugu panelinden iki API jetonuna ihtiyacınız var: biri "Test" türünde, diğeri "Live" türünde (bkz. Yapılandırma). Iugu ikisi için de tek bir API adresi kullanır: faturanın test mi gerçek mi olacağına jeton karar verir. Iugu'da webhook kurmanız gerekmez.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar 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 tamamlandığında Configure düğmesine tıklayın ya da daha sonra modül listesinde VibeFox Iugu Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. Test ve canlı API jetonlarını girin (bkz. Yapılandırma), Test mode seçeneğini açık tutun, Enable / Disable seçeneğini açın ve Save düğmesine tıklayın.

5. Bir test siparişi verin ve Iugu test ödemesiyle Iugu sayfasında ödeyin. Hazır olduğunuzda Test mode seçeneğini kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Iugu payment ve Iugu 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. Iugu, her durumda yalnızca BRL sepetler için sunulur.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Iugu 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 TEST MODE (faturalar test API jetonuyla oluşturulur, gerçek tahsilat yapılmaz) veya LIVE gösterir. Etkin modun jetonu eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve mağazanın varsayılan para birimi BRL değilse (bu durumda Iugu, diğer para birimlerindeki sepetler için sunulmaz) uyarı verir.

Iugu

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

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

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via Iugu. You will be redirected to complete your payment.

API kimlik bilgileri

API jetonlarını Iugu Alia (alia.iugu.com) üzerinde oluşturun: Settings > API integration > New. Bir "Test" türünde ve bir "Live" türünde jeton oluşturun.

Test mode: test API jetonunu kullanır, bu yüzden gerçek tahsilat yapılmaz. Varsayılan: on. Test modu açıkken ödeme sayfasında açıklamanın üstünde SANDBOX — Test mode enabled. No real charges. gösterilir. Bir siparişin durum sorguları ve iadeleri her zaman faturasının oluşturulduğu modun jetonunu kullanır; bu nedenle modu değiştirmek eski siparişleri bozmaz.

Test API token: "Test" türündeki Iugu API jetonu. Test modu açıkken kullanılır.

Live API token: "Live" türündeki (canlı) Iugu API jetonu. Test modu kapalıyken kullanılır. Gizli tutun.

Kaydedilmiş jetonlar 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 jetonu işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş bir alan kaydedilmiş değeri korur.

Ödeme bildirimleri

Notification URL: her fatura, Iugu'ya durum değişikliklerini mağazanızın bu URL'sine bildirmesini söyler. SEO dostu URL'lerle şu şekilde görünür: https://your-shop/module/wcp_iugu_gateway/webhook. Iugu'da yapılandırılacak bir şey yoktur. Aynı URL'yi gösteren, hesap genelinde eklenmiş ek bir tetikleyici (gatilho) zararsızdır. Bildirimler mağazanın güvendiği hiçbir ödeme verisi taşımaz: sipariş oluşturulmadan veya değiştirilmeden önce fatura her zaman Iugu API'sinden yeniden okunur (durum, tutar, para birimi).

Modül, bir fatura durumunu değiştirebilecek Iugu olaylarına yanıt verir: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action ve invoices. Bunların her biri için faturayı okur ve durumunu uygular:

paid: tutar ve para birimi kontrolünden sonra sipariş ödenmiş olarak oluşturulur (veya ödenmiş duruma geçer).

authorized or in_analysis: kart ödemesi tahsilat bekler veya incelemededir. Sipariş beklemeye alınır.

partially_paid: fatura kısmen ödendi. Sipariş beklemeye alınır.

expired: fatura ödenmeden süresi doldu. Bekleyen bir sipariş Payment error alır.

canceled: fatura iptal edildi. Bekleyen bir sipariş iptal edilir.

refunded: fatura Iugu'da iade edildi. Sipariş İade edildi olur.

chargeback: kart sahibi ödemeye itiraz etti. Ödenmiş bir sipariş beklemeye alınır.

Diğer olaylar ve mağazanız tarafından oluşturulmamış faturalar HTTP 200 ile yanıtlanır ve Iugu'ya istek gönderilmeden yok sayılır. Bildirim olmadan bir fatura yalnızca müşteri Iugu sayfasından mağazaya döndüğünde kontrol edilir.

Gelişmiş

Debug log: Iugu isteklerini ve bildirimlerini modül klasöründeki logs/wc_igu_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Jetonlar ve müşteri verileri günlüğe yazılmaz. Hatalar ve uyarılar, anahtar kapalı olsa bile her zaman yazılır. Varsayılan: off.

Log: günlüğün boyutunu ve son kayıtlarını gösterir. Boşaltmak için Clear log düğmesine tıklayın.

Delete Data on Uninstall: açıkken modülü kaldırmak ağ geçidi ayarlarını ve günlüğü siler. Siparişler, Iugu fatura referansları, iadeler ve modülün sipariş durumları her zaman saklanır; bu sayede yeniden kurulumdan sonra eski siparişler çalışmaya devam eder. Varsayılan: off.

Ödeme

Ödeme adımında müşteri ödeme yöntemini (varsayılan olarak Iugu) seçer ve onaylar. Geçerli bir müşteri e-postası gereklidir. Modül, sepet toplamı için BRL cinsinden 3 gün vadeli bir Iugu faturası oluşturur ve müşteriyi Iugu fatura sayfasına yönlendirir. Müşteri orada, Iugu hesabınızda etkin olan yöntemlerle kredi kartı, boleto veya PIX ile öder. Fatura Order # ve sepet numarasını gösterir. Müşterinin adı ve e-postası Iugu'ya gönderilir; ayrıca adresteki Identification number veya VAT number alanından şirket ve CPF/CNPJ bilgisi varsa iletilir. Telefon ve adres yalnızca Iugu'nun kabul ettiği biçimde gönderilir (Brezilya telefon numaraları, 8 haneli CEP'li Brezilya adresleri; kapı numarası s/n olarak gönderilir). Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Iugu onayladığında ödenmiş olarak işaretlenir: fatura, müşteri döndüğünde ve Iugu bir bildirim gönderdiğinde Iugu API'sinden okunur. Ardından sipariş oluşturulur ve müşteri Your payment with Iugu has been received. mesajını içeren standart sipariş onay sayfasını görür.

Müşteri bir boleto veya PIX kodu oluşturup ödemeden önce geri döndüyse, sipariş Awaiting Iugu payment durumunda oluşturulur ve onay sayfası Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. gösterir. Iugu tahsilatı bildirdiğinde, bildirim yoluyla ya da müşteri dönüş bağlantısını yeniden açtığında sipariş Payment accepted durumuna geçer. Müşteri geri döndüğünde Iugu'ya henüz ulaşılamadıysa, Payment confirmation sayfası We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. mesajını, Check again düğmesini ve Back to checkout düğmesini gösterir. Faturası iptal edilmiş veya ödenmeden süresi dolmuş bir siparişin onay sayfasında Your Iugu payment was not completed. Please contact us about this order. görünür.

Fatura, sipariş oluşmadan önce iptal edilmiş veya süresi dolmuşsa, müşteri ödeme sayfasına The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. mesajıyla döner. Sepet korunur. Müşteri yeniden ödediğinde, tutar ve mod değişmemişse modül onu aynı açık faturaya yönlendirir. Aksi halde eski faturayı Iugu'da iptal eder ve yenisini oluşturur; böylece aynı sepet iki açık fatura üzerinden ödenemez. Eski bir fatura yine de ödenirse, ödeme sepetle eşleştirilmeye devam eder.

Iugu faturayı oluşturamazsa, müşteri kısa bir mesajla ödeme sayfasında kalır; örneğin nedeni ve fatura bilgilerini kontrol etme isteğiyle birlikte Iugu could not create the invoice: ya da Could not connect to Iugu. Please try again in a moment. Teknik neden günlüğe yazılır.

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

Modül yalnızca tek seferlik ödemeleri destekler. Sitede kart formu, kayıtlı kartlar, abonelikler veya yinelenen faturalama, carnê (ödeme defteri), bölünmüş ödemeler veya taksit ayarları yoktur; taksit için Iugu sayfasının ayarlarını kullanın. Iugu sayfasında sunulan ödeme yöntemleri modül ayarlarından seçilemez: Iugu hesabınızda etkin olan tüm yöntemler sunulur. Payment error veya Canceled durumundaki bir sipariş mağazadan yeniden ödenemez; müşteri yeni bir sipariş verir.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri Iugu'ya yönlendirildi ve henüz ödeme yapmadı ya da Iugu ödemeyi henüz onaylamadı. Yalnızca sepet vardır.

Payment accepted: Iugu ödemeyi onayladı. Ödeme, işlem kimliği olarak Iugu fatura kimliğiyle kaydedilir; bir not fatura kimliğini ve ödeme yöntemini (kredi kartı, boleto veya PIX) gösterir.

Awaiting Iugu payment: müşteri düzenlenmiş bir boleto veya PIX ile geri döndü. Iugu ödemeyi bildirdiğinde sipariş Payment accepted durumuna geçer.

Iugu payment on hold: kart ödemesi yetkilendirildi ama henüz tahsil edilmedi (Iugu'da tahsil edin; Iugu faturayı ödenmiş olarak bildirdiğinde sipariş tamamlanır), ödeme incelemede, fatura yalnızca kısmen ödendi, bir chargeback açıldı, Iugu sepetten farklı bir tutar veya para birimi bildirdi (örneğin fatura oluşturulduktan sonra sepet değiştirildiyse) ya da ödeme sipariş iptal edildikten sonra geldi. Notlar nedenini açıklar. Siparişi kontrol edin ve yerine getirin ya da ödemeyi iade edin.

Payment error: bekleyen bir siparişin faturası ödenmeden süresi doldu. Iugu faturayı daha sonra ödenmiş olarak bildirirse, sipariş Payment accepted durumuna geçer.

Canceled: bekleyen bir siparişin faturası Iugu'da iptal edildi.

Refunded: ödeme modül üzerinden ya da Iugu panelinde tamamen iade edildi.

Aynı sepetin başka bir faturası da ödenirse, sipariş değişmez. Bir not, mükerrer ödemeyi Iugu'da iade etmenizi ister.

Iugu ödeme bloğu

Sipariş sayfası, Iugu fatura kimliğini (Iugu'daki faturaya bağlantılı), ödeme yöntemini, durumu, Iugu'nun tahsil ettiği tutarı ve iade edilen tutarı, test faturaları için bir Test mode rozetini, iade geçmişini ve siparişin Iugu notes bölümünü içeren bir Iugu payment bloğu gösterir.

İadeler

Iugu payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Iugu düğmesine tıklayın. Refund this amount through Iugu? This cannot be undone. sorusunu onaylayın. Siparişleri düzenleme yetkisine sahip olmanız gerekir. İade, faturanın oluşturulduğu modun jetonuyla gönderilir; bu nedenle o jeton ayarlanmış olmalıdır.

Kredi kartı: tam veya kısmi iadeler.

PIX: yalnızca tam iadeler.

Boleto: Iugu üzerinden iade edilemez. Parayı müşteriye banka havalesiyle geri gönderin.

İadeler, Iugu'nun faturadan gerçekten tahsil ettiği tutardan hesaplanır; bu nedenle bir tutar uyuşmazlığından sonra, sipariş toplamına değil müşterinin ödediği tutara kadar iade yapabilirsiniz. Yalnızca ödenmiş faturalar iade edilebilir ve Iugu'da hâlâ iade edilebilir olan tutarı aşamaz. İade, ancak Iugu onayladığında tamamlanmış sayılır. Iugu iadeyi reddeder veya onaylamazsa, blok hatayı gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, fatura kimliği ve nedeniyle birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded olarak ayarlar. Kısmi iade durumu değiştirmez. İadeler, Iugu faturayı ödenmiş olarak bildirdikten sonra kullanılabilir.

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

Iugu panelinde yapılan tam bir iade, siparişi bir notla birlikte Refunded olarak ayarlar. Panelde yapılan kısmi iadeler içe aktarılmaz.

Lisans anahtarı

Modül, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Iugu Gateway lisans bloğu, Modules > Module Manager > VibeFox Iugu Gateway > Configure sayfasında ayarların üstünde ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskeli olarak, durumu (örneğin lisansın geçerli olduğu tarihi ve alan adınızı) ve Check now (durumu yeniden kontrol eder), Change key (başka bir anahtar girer) ve Remove key (anahtarı bu mağazadan kaldırır) düğmelerini gösterir. Bunların altında Product: presta-payment-iugu satırı ve Manage licenses and domains in your account bağlantısı bulunur; bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca modül için Configure izni olan çalışanlar değiştirebilir. Bloğun metinleri yönetim paneli 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 veya 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 duruma göre çalışmaya devam eder.

Bir anahtar bir alan adında çalışır: ana mağazanın alan adında, çoklu mağaza kurulumunda da. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan Iugu, ö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. PrestaShop vitrini yönetim paneline giriş yaptığınızı bilmez, bu nedenle ödeme yöntemi sizin için de gizlenir: modülü anahtar satın almadan önce kurabilirsiniz, ancak ödeme sayfasında test edemezsiniz. Modules > Module Manager sayfasında 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.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum, yönetim panelinde ç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

Iugu ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu ve etkin modun jetonunun ayarlandığını kontrol edin: test modunda Test API token, canlı modda Live API token. Sepet para birimi BRL olmalı ve toplam en az R$ 1,00 olmalıdır. Payment > Preferences bölümünde modülün BRL para birimi, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin. Jeton veya para birimi yanlışsa ayarlar sayfası bir uyarı gösterir.

Ödeme yapıldı ama sipariş oluşmadı: Iugu'dan gelen bildirim mağazanıza ulaşmadı ya da kontrol edilemedi. Debug log seçeneğini açın ve modül sayfasındaki Log alanına bakın. Mağazanızın Notification URL adresinden internet üzerinden erişilebilir olduğunu ve faturanın oluşturulduğu modun jetonunun hâlâ girili olduğunu kontrol edin. Fatura, müşteri ödemeden sonra mağazaya döndüğünde de kontrol edilir.

Notification answers verification failed: fatura o anda Iugu API'sinden okunamadı; örneğin bir ağ hatası, yanlış bir jeton veya faturanın modu için jetonun eksik olması nedeniyle. Iugu bildirimi yeniden dener.

Notification answers busy: sepet aynı anda başka bir istek tarafından işleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışıysa). Iugu bildirimi yeniden dener. Günlük nedeni gösterir.

Notification answers invalid invoice id: bildirimde geçerli bir fatura kimliği yoktu. Hiçbir şey değişmez.

Sipariş Iugu payment on hold durumunda: sipariş bloğundaki Iugu notes bölümünü okuyun. Kart ödemesi tahsilat bekliyor, ödeme incelemede, kısmen ödenmiş ya da itiraz edilmiş olabilir; ödenen tutar sepetle eşleşmiyor olabilir ya da ödeme sipariş iptal edildikten sonra gelmiş olabilir.

Müşteri «Iugu payments are not available right now» mesajını görüyor: API jetonu eksik veya yanlış. Etkin modun jetonunu kontrol edin.

Müşteri «This order already has an Iugu payment that the store has to review» mesajını görüyor: sepetin daha önceki bir faturası yetkilendirilmiş, incelemede veya kısmen ödenmiş, ancak sipariş oluşturulamamış. Iugu'daki faturayı ve günlüğü kontrol edin.

İade başarısız: bloktaki mesajı okuyun. Boleto ödemeleri Iugu üzerinden iade edilemez, PIX ödemeleri yalnızca tam iade edilebilir ve yalnızca ödenmiş faturalar iade edilebilir. Mesaj, ödemenin test veya canlı modda yapıldığını ve bu mod için bir jeton ayarlanmadığını söylüyorsa, o modun jetonunu girin. Iugu iadeyi onaylamadıysa, yeniden denemeden önce Iugu'daki faturayı kontrol edin.

Geliştiriciler fatura isteğini değiştirebilir; örneğin actionWcpIuguInvoiceData kancasında payable_with ile ödeme yöntemlerini sınırlayabilirler.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Iugu 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, sonraki bir yeniden kurulum için tüm ayarlar saklanır. Iugu fatura referansları ve iadeler ile Awaiting Iugu payment ve Iugu payment on hold sipariş durumları her zaman saklanır; böylece daha önce ödenmiş siparişler hâlâ iade edilebilir ve geç gelen bildirimler yeniden kurulumdan sonra da eşleşmeye devam eder. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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