VibeFox Viva Wallet 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.

Viva hesabı: bir Viva satıcı hesabı. Testler için bir demo hesabı (demo.vivapayments.com), gerçek ödemeler için canlı bir hesap (www.vivapayments.com) kullanabilirsiniz. Her hesabın kendi kimlik bilgileri vardır. Ödemeler için Smart Checkout kimlik bilgilerine (Client ID ve Client Secret) ve bir ödeme kaynağının Source Code değerine ihtiyacınız vardır. Merchant ID ve API Key isteğe bağlıdır: yalnızca Viva'nın webhook URL doğrulamasını yanıtlamak için kullanılırlar.

Para birimi: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK veya CHF. Diğer para birimlerinde ödeme yöntemi ödeme adımında gizlenir.

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 tamamlandığında Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox Viva Wallet Gateway öğesini bulup Configure düğmesine tıklayın.

3. Configure 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. Viva'nın demo ve/veya canlı hesabının kimlik bilgilerini girin; ödeme kaynağını ve webhook'u Viva hesabınızda ayarlayın (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test Mode açıkken bir Viva demo kartıyla demo ödemesi yapın, ardından canlıya geçmek için Test Mode seçeneğini kapatın.

Kurulumda modül Viva Wallet payment on hold sipariş durumunu oluşturur. Modül, kurulum sırasında etkin olan ülkeler için sunulur. Para birimlerini, ülkeleri ve müşteri gruplarını Payment > Preferences bölümünden değiştirebilirsiniz; yeni ülkeleri sonradan orada ekleyebilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Viva Wallet 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, mevcut modda Client ID, Client Secret veya Source Code yoksa (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., ya da canlı modda Live) ve mağazanın varsayılan para birimi desteklenmiyorsa sizi uyarır. Test modu açıkken Test mode is on: payments go to the Viva demo environment. ifadesini gösterir. Ayarları kaydetmek, önbelleğe alınmış Viva erişim belirteçlerini siler; böylece yeni kimlik bilgileri hemen kullanılır.

Viva Wallet

Enable/Disable: Enable Viva Wallet payment gateway ödeme yöntemini açar veya kapatır. Varsayılan: kapalı.

Title: müşterinin ödeme adımında gördüğü ödeme yöntemi adı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Viva Wallet. Zorunlu: boş bir başlık kaydedilmez ve sayfa Enter a title for the payment method. ifadesini gösterir.

Description: ödeme adımında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Viva demo ortamını kullanır (demo.vivapayments.com). Yeni ödemeler ve API çağrıları demo hesabının kimlik bilgilerini kullanır. Gerçek para çekilmez ve ödeme adımında müşteriler (Test mode: use Viva demo cards, no real money is charged.) ifadesini görür. Varsayılan: açık. Gerçek ödemeleri canlı hesapla almak için kapatın. Daha önce yapılmış ödemeler, yapıldıkları ortamda doğrulanmaya ve iade edilmeye devam eder.

Demo hesabı (test modu) ve canlı hesap

İki bölümün alanları aynıdır: biri demo hesabı, diğeri canlı hesap içindir. Viva hesabınızda Settings > API Access bölümünü açın ve Smart Checkout kimlik bilgilerini (Client ID, Client Secret), Merchant ID ve API Key değerlerini kopyalayın. Source Code, Sales > Online payments > Websites / apps bölümündedir.

Client ID (Demo) / Client ID (Live): hesabın Smart Checkout OAuth 2.0 Client ID değeri. Ödemeler için gereklidir.

Client Secret (Demo) / Client Secret (Live): hesabın Smart Checkout OAuth 2.0 Client Secret değeri. Ödemeler için gereklidir.

Source Code (Demo) / Source Code (Live): hesabın ödeme kaynağının 4 haneli kodu. Success URL ve Failure URL'leri bu mağazaya işaret etmelidir (aşağıya bakın). Ödemeler için gereklidir.

Merchant ID (Demo) / Merchant ID (Live): isteğe bağlı. Yalnızca Viva'nın webhook URL doğrulamasını yanıtlamak için kullanılır.

API Key (Demo) / API Key (Live): isteğe bağlı. Yalnızca Viva'nın webhook URL doğrulamasını yanıtlamak için kullanılır.

Kaydedilmiş Client Secret ve API Key değerleri bir daha asla 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 secrets: bir gizli değeri işaretleyip Save düğmesine tıklayarak kaldırın. Boş bir alan, kayıtlı değeri korur.

Dönüş URL'leri ve webhook

Addresses for the Viva account: bu alan, Viva hesabına girmeniz gereken mağaza adreslerinizin üçünü gösterir. Dostu URL'lerle şöyle görünürler: https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail ve https://your-shop/module/wcp_viva_gateway/webhook; başlarında /en/ gibi bir dil kodu da olabilir. Ayarların gösterdiği gibi birebir kopyalayın.

Payment source: kullandığınız her hesapta Sales > Online payments > Websites / apps bölümünde mağazanızın alan adı için bir ödeme kaynağı oluşturun. Success URL ve Failure URL olarak, başarı ve hata adreslerinin alan adından sonraki kısmını girin.

Webhook: Settings > API Access > Webhooks bölümünde şu olaylar için webhook adresini ekleyin:

Viva, URL'yi kaydetmeden önce kontrol eder. Modül, hesabınızın doğrulama anahtarıyla yanıt verir: anahtarı mevcut modun Merchant ID ve API Key değerleriyle alır ya da aşağıda girilen anahtarı kullanır. Webhook'lar, müşteri tarayıcıyı kapatsa bile ödemeleri onaylar. Viva webhook'ları imzalanmadığı için modül webhook'a tek başına asla güvenmez: her ödeme, sipariş oluşturulmadan önce Viva API'si ile doğrulanır. Webhook olmadan, sipariş yalnızca müşteri ödeme yaptıktan sonra mağazaya döndüğünde oluşturulur.

Webhook Verification Key: isteğe bağlı. Anahtarı mevcut modun Merchant ID ve API Key değerleriyle otomatik almak için boş bırakın ya da Viva hesabınızın doğrulama anahtarını buraya yapıştırın.

Gelişmiş ayarlar

Order Status After Payment: başarılı bir ödemeden sonra ayarlanan sipariş durumu. Durum hemen ayarlanır; ikinci bir durum değişikliği yapılmaz.

Brand Color: Viva ödeme sayfası için 6 haneli bir HEX renk kodu, örneğin 0000ff. Baştaki # kaldırılır. Varsayılan renk için boş bırakın. Başka bir değer kaydedilmez: sayfa Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept. ifadesini gösterir.

Debug Logging: API isteklerini modül klasöründeki logs/viva_wp_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Anahtarlar, belirteçler ve müşteri verileri kaydedilmez. Hatalar bu seçenek kapalı olsa bile her zaman kaydedilir. Varsayılan: kapalı.

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

Delete Data on Uninstall: açıkken modül kaldırıldığında ayarlar ve modül günlükleri silinir. Siparişler ve ödeme verileri (Viva ödeme denemeleri, iadeler, sipariş durumu) asla silinmez. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Viva Wallet) ve You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). notunu görür. Onayladıktan sonra modül, sepet tutarı için sepet para biriminde bir Viva ödeme siparişi oluşturur ve müşteriyi Viva Smart Checkout sayfasına gönderir. Orada müşteri, Viva hesabınızda etkinleştirilmiş yöntemlerden biriyle öder. Müşterinin e-postası, adı, telefonu ve ülkesi Viva'ya iletilir; Viva destekliyorsa sayfa sepetin dilinde açılır. Viva'da ödeme Cart #, sepet numarası ve mağazanızın adıyla görünür. Viva ödeme siparişi 30 dakika sonra sona erer. Bu noktada henüz bir sipariş yoktur.

Ödeme yaptıktan sonra müşteri mağazanıza döner. Sipariş, yalnızca Viva onayladıktan sonra ödenmiş olarak işaretlenir: modül işlemi dönüşte ve webhook'ta Viva API'sinden yeniden okur. Ardından sipariş oluşturulur ve müşteri standart sipariş onay sayfasını görür. Ödeme henüz onaylanmamışsa, Payment confirmation sayfası We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. mesajını ve Check again ile Back to checkout düğmelerini gösterir; Viva ödemeyi onayladığı anda webhook siparişi oluşturur.

Ödeme başarısız olursa veya müşteri Viva sayfasında iptal ederse sipariş oluşturulmaz ve sepet korunur. Müşteri The Viva Wallet payment was not completed. Please try again or choose another payment method. ya da The Viva Wallet payment was cancelled. You can try again or choose another payment method. mesajıyla ödeme adımına döner ve yeniden ödeme yapabilir.

Viva ödemeyi başlatamazsa müşteri Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (eksik veya hatalı kimlik bilgileri) ya da We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. mesajıyla ödeme adımında kalır. Teknik neden günlüğe yazılır.

Dönüş sayfaları sipariş onayını yalnızca ödeme yapan müşteriye gösterir. Dönüş adresini açan herkes, sipariş ayrıntısı olmadan sipariş geçmişine veya ödeme adımına yönlendirilir.

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

Modül yalnızca tek seferlik ödemeleri kabul eder; bunlar Viva sayfasında hemen tahsil edilir. Ön yetkilendirme ve tahsilat, taksit, kayıtlı kart, abonelik, Viva Native Checkout (kendi sayfanızdaki kart alanları) veya POS terminalleri yoktur. Müşteri yeni bir deneme başlattığında, eski ödenmemiş Viva ödeme siparişi iptal edilmez; Viva onu 30 dakika sonra sona erdirir.

Siparişler ve iadeler

Sipariş durumları

Henüz sipariş yok: müşteri Viva'ya yönlendirildi ve ödeme yapmadı, ödeme başarısız oldu ya da iptal edildi, veya Viva ödemeyi henüz tamamlamadı. Yalnızca sepet vardır ve müşteri yeniden ödeme yapabilir.

Payment accepted, Delivered veya Viva Wallet payment on hold: ödeme onaylandı. Durum Order Status After Payment ayarını izler. Ödeme, Viva işlem kimliğiyle kaydedilir ve bir notta tutar, işlem, Viva sipariş kodu, ortam (demo veya canlı) ve onayın nasıl alındığı (webhook veya müşterinin dönüşü) gösterilir.

Uyuşmazlıktan sonra Viva Wallet payment on hold: Viva, sepet tutarından veya para biriminden farklı bir tutar ya da para birimi bildirdi; örneğin müşteri ödemeye başladıktan sonra sepet değiştirildiğinde. Sipariş, kaydedilmiş bir ödeme olmadan oluşturulur ve Viva Wallet payment held for review notu nedenini belirtir. Müşteri, Viva onayına dair bir söz olmadan standart sipariş onay sayfasını görür. Viva panelindeki ödemeyi siparişle karşılaştırın ve siparişi işleyin ya da ödemeyi manuel olarak iade edin. Aynı sepete ait eşleşen bir ödeme daha sonra gelirse sipariş ödenmiş duruma geçer.

İptal edilmiş veya iade edilmiş bir siparişe gelen ödeme, sipariş durumunu değiştirmez; bir not, siparişi geri yüklemenizi veya ödemeyi Viva panelinde iade etmenizi ister. Zaten ödenmiş bir siparişe ikinci bir ödeme gelirse sipariş değiştirilmez; bir not, mükerrer ödemeyi Viva panelinde iade etmenizi ister.

Viva Wallet payment bloğu

Sipariş sayfasında, Viva sipariş kodu, işlem kimliği, ortam ve Source Code, Viva durumu, ödenen ve iade edilen tutarlar, demo ödemeler için bir Demo rozeti, iade geçmişi, sepetin ödeme denemeleri (birden fazlaysa) ve siparişin Viva Wallet notes notlarını içeren bir Viva Wallet payment bloğu bulunur.

İadeler

Viva Wallet payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Viva Wallet düğmesine tıklayın. Refund this amount via Viva Wallet? This cannot be undone. sorusunu onaylayın. Onaylanmış bir Viva işlemi olan siparişlerde tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modüllere erişim gerekmez. Sipariş daha sonra düzenlenmiş olsa bile, Viva'nın ödeme için tahsil ettiği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı hesaba (demo veya canlı), ödemenin para biriminde gönderilir; bu nedenle o hesabın Client ID ve Client Secret değerleri girilmiş olmalıdır. Viva iadeyi kabul etmezse blok hatayı gösterir ve iade kaydedilmez. Başarılı bir iade, iade geçmişine ve notlara Viva iade işlemiyle birlikte eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. Onaylı ödemesi olmadan inceleme için beklemeye alınmış bir sipariş bu bloktan iade edilemez.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Viva üzerinden para geri göndermez. Viva panelinde yapılan iadeler içe aktarılmaz. Gerekirse siparişi manuel olarak güncelleyin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Viva Wallet Gateway lisans bloğu, Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure sayfasında ayarların üstünde yer alan ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok, anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarih ve alan adınız) ve şu düğmeleri gösterir: 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-viva satırı ve vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure yetkisine sahip çalışanlar değiştirebilir. Bloktaki metinler 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 tarihli License expired on. Mağaza adresi değiştikten sonra veya hesabınızda bir alan adı yuvası boşalttıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa modül son bilinen durumla çalışmaya devam eder.

Bir anahtar yalnızca 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 boşaltın.

Etkin bir anahtar olmadan Viva Wallet ö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 yönetim paneline giriş yaptığınızı bilmez, bu nedenle ödeme yöntemi sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme adımında test edemezsiniz. Modules > Module Manager bölümünde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler Viva webhook'u ve mağazaya dönüşle onaylanmaya devam eder, iadeler de ç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, 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

Viva Wallet ödeme adımında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve mevcut modun Client ID, Client Secret ve Source Code değerlerine sahip olduğunu kontrol edin (test modunda Demo alanları, canlı modda Live alanları). Sepet para birimi EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK veya CHF'den biri olmalıdır. 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. Kimlik bilgileri eksikse ayarlar sayfası uyarı gösterir.

Ödeme gerçekleşti, ancak sipariş oluşturulmadı: webhook çalışmıyor. Viva'da kullandığınız hesapta (demo veya canlı) webhook'un var olduğunu, URL'sinin ayarlarda gösterilenle birebir aynı olduğunu ve Transaction Payment Created seçili olduğunu kontrol edin. O ödemenin hesabının Client ID ve Client Secret değerlerinin hâlâ girili olduğunu kontrol edin: modül ödemeyi doğrulamak için bunlara ihtiyaç duyar. Debug Logging seçeneğini açın ve Log alanına bakın. Müşteri ödeme yaptıktan sonra mağazaya döndüğünde de sipariş oluşturulur.

Viva webhook URL'sini doğrulayamıyor: mevcut modun Merchant ID ve API Key değerlerini girin (ya da doğrulama anahtarının kendisini Webhook Verification Key alanına), kaydedin, ardından Viva'da yeniden doğrulayın. Diğer hesabın webhook'unu doğrulamak için önce Test Mode seçeneğini değiştirin ya da o hesabın anahtarını girin.

Webhook bir hatayla yanıt veriyor: Viva, mağazanızın yanıtını gösterir ve başarısız webhook'ları yeniden dener. verification_failed (HTTP 500), ödemeyi doğrulamak için Viva API'sine ulaşılamadığı ya da siparişin oluşturulamadığı anlamına gelir (örneğin modül devre dışıysa). busy (HTTP 503), siparişin aynı anda başka bir istek tarafından işlendiği anlamına gelir. transaction_not_found (HTTP 404), işlemin o ödemenin hesabında bulunmadığı anlamına gelir; örneğin hatalı kimlik bilgileri nedeniyle. Aynı Viva hesabındaki diğer mağazaların ödemeleriyle ilgili olaylar ignored yanıtı alır.

Müşteri Viva Wallet seçerken hata görüyor: modül sayfasındaki Log alanına bakın. Hatalı bir Client ID veya Client Secret, Viva Wallet ödemelerinin kullanılamadığı mesajını gösterir. Viva'ya ulaşılamazsa ya da ödeme siparişini reddederse (örneğin Source Code başka bir hesaba aitse), müşteri mağazanın Viva Wallet'a bağlanamadığı mesajını alır.

Müşteri döner ve şunu görür: We could not find your order. If you were charged, please contact us.: dönüş adresindeki Viva sipariş kodu, bu mağazanın bir ödemesi değildir; örneğin başka bir mağazanın ödeme kaynağı buraya işaret ediyorsa. Ödeme kaynağının Success URL ve Failure URL değerlerini kontrol edin.

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

Şu hatayla iade başarısız oluyor: This payment was made in the Viva demo (or live) environment: ödemenin yapıldığı hesabın Client ID ve Client Secret değerleri girilmemiş. Bunları girin ve yeniden deneyin. Diğer iade hataları, HTTP kodunu ve Viva'nın mesajını gösterir.

Blok şunu diyor: Transaction ID not found. Cannot process refund.: siparişin onaylı bir Viva ödemesi yok; örneğin bir tutar uyuşmazlığından sonra. Gerekirse ödemeyi Viva panelinde iade edin.

Kaldırma

Modülü devre dışı bırakmak tüm verileri korur; yalnızca önbelleğe alınmış Viva erişim belirteçleri silinir. Modülü kaldırmak için Modules > Module Manager bölümüne gidin, VibeFox Viva Wallet 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 silinir. Önbelleğe alınmış erişim belirteçleri ve webhook anahtarları her zaman silinir. Delete Data on Uninstall açıksa ayarlar ve günlük silinir. Kapalıysa, sonraki bir yeniden kurulum için tüm ayarlar saklanır. Viva ödeme denemeleri ve iadeleri ile Viva Wallet payment on hold sipariş durumu her zaman korunur; bu nedenle önceden ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler, ödeme notlarını ve işlem kimliklerini korur.

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