VibeFox Viva Wallet for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

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 bilgileri (Client ID ve Client Secret) ile bir ödeme kaynağının Source Code değeri gerekir. 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.

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

Herkese açık HTTPS sitesi: webhook'lar için sitenizin internetten HTTPS üzerinden erişilebilir olması gerekir.

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

Kurulum

1. WordPress'te Plugins > Add New > Upload Plugin bölümüne gidin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_viva_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 > Viva Wallet > Manage, ya da Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

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

5. Viva demo ve/veya canlı hesabının kimlik bilgilerini girin; ödeme kaynağını ve webhook'u ayarlayın (bkz. Yapılandırma).

6. Enable/Disable seçeneğini açın. Test Mode açıkken bir Viva demo kartıyla demo ödeme yapın, ardından canlıya geçmek için Test Mode seçeneğinin işaretini kaldırın.

Yapılandırma

Tüm ayarlar tek bir sayfada bulunur: WooCommerce > Settings > Payments > Viva Wallet. Alanların üzerinde sayfa, geçerli 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ğaza para birimi desteklenmiyorsa sizi uyarır. Test modu açıkken Test mode is on: payments go to the Viva demo environment. ibaresini gösterir. Ödeme yöntemleri listesinde, geçerli mod bu üç değere sahip olana kadar Viva Wallet kurulum gerektiriyor olarak işaretlenir.

Genel

Enable/Disable: Enable Viva Wallet payment gateway ö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: Viva Wallet.

Description: ödeme sayfası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: Use the Viva demo environment (demo.vivapayments.com). Yeni ödemeler ve API çağrıları demo hesabının kimlik bilgilerini kullanır. Gerçek para tahsil edilmez ve ödeme sayfasında açıklama (Test mode: use Viva demo cards, no real money is charged.) ifadesiyle biter. Varsayılan: açık. Gerçek ödemeleri canlı hesapla almak için işareti kaldırı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ümde de aynı alanlar bulunur: demo hesabı için bir set, canlı hesap için bir set. 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ünde bulunur.

Client ID (Demo) / Client ID (Live): hesabın Smart Checkout OAuth 2.0 Client ID değeri. Zorunlu.

Client Secret (Demo) / Client Secret (Live): hesabın Smart Checkout OAuth 2.0 Client Secret değeri. Zorunlu.

Source Code (Demo) / Source Code (Live): hesabın ödeme kaynağının 4 haneli kodu. Success URL ve Failure URL adresleri bu mağazaya işaret etmelidir (aşağıya bakın). Zorunlu.

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.

Dönüş URL'leri ve webhook

Payment source: Sales > Online payments > Websites / apps bölümünde, kullandığınız her hesapta mağazanızın alan adı için bir ödeme kaynağı oluşturun. Success URL ve Failure URL olarak, ayarlarda gösterilen ve şu biçimde görünen iki adresin alan adından sonraki yolları girin: https://your-site/wc-api/viva_payment_success/ ve https://your-site/wc-api/viva_payment_fail/.

Webhook: Settings > API Access > Webhooks bölümüne, ayarlarda gösterilen ve şu biçimde görünen URL'yi ekleyin: https://your-site/wp-json/wc-viva-gateway/v1/webhook; şu olaylar için:

Viva, URL'yi kaydetmeden önce kontrol eder. Eklenti, hesabınızın doğrulama anahtarıyla yanıt verir: anahtarı geçerli modun Merchant ID ve API Key değerleriyle alır veya aşağıda girilen anahtarı kullanır. Webhook'lar, müşteri tarayıcıyı kapatsa bile ödemeleri onaylar. Viva webhook'ları imzalanmadığı için eklenti webhook'a tek başına asla güvenmez: her ödeme, sipariş ödenmiş olarak işaretlenmeden önce Viva API'si üzerinden doğrulanır. Webhook olmadan bir sipariş, yalnızca müşteri ödemeden sonra mağazaya döndüğünde onaylanır.

Webhook Verification Key: isteğe bağlı. Anahtarı geçerli 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 # işareti kaldırılır. Varsayılan renk için boş bırakın. Başka her değer kaydetme sırasında reddedilir ve önceki değer korunur.

Debug Logging: Enable logging API isteklerini WooCommerce > Status > Logs altına, kaynak wcp_viva_gateway olarak yazar. Anahtarlar ve müşteri verileri kaydedilmez. Hatalar bu seçenek kapalı olsa bile her zaman kaydedilir. Varsayılan: kapalı.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Açıkken eklentiyi silmek ayarları, ödeme denemeleri tablosunu ve eklenti günlüklerini kaldırır. Sipariş notları ve sipariş verileri kalır. Varsayılan: kapalı.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Viva Wallet) ve siparişi verir. Eklenti, sipariş tutarı için sipariş para biriminde bir Viva ödeme siparişi oluşturur ve müşteriyi Viva Smart Checkout sayfasına yönlendirir. Orada müşteri, Viva hesabınızda etkinleştirilmiş yöntemlerden biriyle (kartlar, Apple Pay veya Google Pay gibi) öder. Müşterinin e-posta, ad, telefon ve ülke bilgileri Viva'ya aktarılır; sayfa, Viva destekliyorsa sitenizin dilinde, desteklemiyorsa İngilizce açılır. Ödeme Viva'da WooCommerce # ve sipariş numarası olarak görünür. Viva ödeme siparişi 30 dakika sonra sona erer.

Ödemeden sonra müşteri mağazanızın sipariş alındı sayfasına döner. Sipariş, yalnızca Viva onayladıktan sonra ödenmiş olarak işaretlenir: eklenti işlemi Viva API'sinden, müşterinin dönüşünde ve webhook'ta yeniden okur. Ödeme henüz onaylanmamışsa sayfa We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. mesajını gösterir.

Ödeme başarısız olursa veya müşteri Viva sayfasında iptal ederse sipariş durumu değişmez. Müşteri, The Viva Wallet payment was not completed. Please try again or choose another payment method. veya The Viva Wallet payment was cancelled. You can try again or choose another payment method. mesajıyla Pay for order sayfasına yönlendirilir ve tekrar ödeyebilir.

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

Ödeme yöntemi klasik ödeme sayfasında, Ödeme bloğunda ve siparişin para biriminin kontrol edildiği Pay for order sayfasında çalışır. High-Performance Order Storage (HPOS) ile uyumludur.

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

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri Viva'ya yönlendirildi ve henüz ödeme yapmadı, ödeme henüz onaylanmadı ya da ödeme başarısız oldu veya iptal edildi. Bir not, Viva ödeme siparişini ve ortamı (demo veya canlı) gösterir. Başarısız ve iptal edilen denemeler sipariş notlarına eklenir ve müşteri tekrar ödeyebilir.

Processing, Completed or On Hold: ödeme onaylandı. Durum, Order Status After Payment ayarını izler. Sipariş notu tutarı, Viva işlem kimliğini, ortamı ve onayın nasıl alındığını (webhook veya müşterinin dönüşü) gösterir.

On hold for review: Viva, siparişin toplam tutarından farklı bir tutar veya para birimi bildirdi; örneğin müşteri ödemeye başladıktan sonra sipariş düzenlendiğinde. Viva Wallet payment held for review notu nedeni belirtir. Viva panelindeki ödemeyi siparişle karşılaştırın ve siparişi tamamlayın ya da ödemeyi manuel olarak iade edin.

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

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Viva Wallet düğmesine tıklayın. Doğrulanmış bir Viva işlemi olan siparişler için tam ve kısmi iadeler desteklenir. İ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 WooCommerce hatayı gösterir ve iade kaydedilmez. Başarılı bir iade, Viva iade işlemiyle birlikte sipariş notlarına eklenir.

Viva panelinde yapılan iadeler içe aktarılmaz. Gerekirse Refund via Viva Wallet kullanmadan WooCommerce'de manuel bir iade oluşturun.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu, WooCommerce > Settings > Payments > Viva Wallet sayfasının üst kısmındadır. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blokta durum gösterilir; örneğin lisansın hangi tarihe kadar aktif olduğu ve alan adınız. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key, 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 tek bir alan adında çalışır. Anahtarı bir siteden kaldırmak, alan adı hakkını serbest bırakmaz. Hakkı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan Viva Wallet, ö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, bir anahtar satın almadan önce eklentiyi kurup test edebilmeniz için ödeme yöntemini (unlicensed — visible to admins only) ibaresiyle işaretlenmiş olarak görmeye devam eder. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma çıkar. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Bir lisans sona erdiğinde eklenti çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum arka planda otomatik olarak yeniden kontrol edilir.

Sorun giderme

Viva Wallet ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve geçerli modda Client ID, Client Secret ve Source Code değerlerinin bulunduğunu kontrol edin (test modunda Demo alanları, canlı modda Live alanları). Mağaza para birimi (Pay for order sayfasında sipariş para birimi) EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK veya CHF'den biri olmalıdır. Ayarlar sayfası eksik bir şey olduğunda uyarı gösterir.

Ödeme yapıldı ama sipariş Pending payment durumunda kaldı: 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çeneğinin işaretli olduğunu kontrol edin. O ödemenin hesabının Client ID ve Client Secret değerlerinin hâlâ girili olduğunu doğrulayın: eklenti ödemeyi doğrulamak için bunlara ihtiyaç duyar. Ayrıntılar WooCommerce > Status > Logs altında, kaynak wcp_viva_gateway olarak bulunur.

Viva webhook URL'sini doğrulayamıyor: geçerli modun Merchant ID ve API Key değerlerini (ya da doğrulama anahtarının kendisini Webhook Verification Key alanına) girin, kaydedin ve 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 veya 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ığı anlamına gelir. 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 ödemelerine ait olaylar ignored yanıtı alır.

Müşteri sipariş verirken bir hata görüyor: Debug Logging seçeneğini açın ve WooCommerce > Status > Logs sayfasında, kaynak wcp_viva_gateway, kayıtlara bakın. Hatalı bir Client ID veya Client Secret ya da eksik bir Source Code, Viva Wallet ödemelerinin kullanılamadığı mesajına yol açar. Viva'ya ulaşılamazsa veya ö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.

Ödemeden sonra sipariş On hold durumunda: sipariş notunu okuyun. Ödenen tutar veya para birimi siparişten farklıydı. Siparişi tamamlayın veya ödemeyi iade edin.

İade şu hatayla 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ı, Viva'nın HTTP kodunu ve mesajını gösterir.

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

Geliştiriciler için: viva_wp_supported_currencies filtresi, Viva hesabınızın desteklediği ek para birimlerini etkinleştirir; viva_wp_create_order_payload ödeme siparişi isteğini değiştirir (tutar, para birimi ve Source Code aynı kalmalıdır); viva_wp_icon ise ödeme sayfasındaki simgeyi değiştirir.

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur; yalnızca önbelleğe alınmış Viva erişim belirteçleri kaldırılır. Tamamen kaldırmak için eklentiyi Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu ile önbelleğe alınmış belirteçler ve webhook anahtarları her zaman kaldırılır. Ayarlar, ödeme denemeleri tablosu ve eklenti günlükleri (döndürülmüş dosyalar dahil günlük dosyaları ve veritabanı kayıtları) 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ı ve işlem kimliklerini korur.

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