VibeFox Worldline for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

WooCommerce: 7.0 veya üzeri, kurulu ve etkin olmalıdır. Eklenti, WooCommerce olmadan etkinleştirilmez.

PHP: 8.0 veya üzeri.

Worldline hesabı: bir Worldline Direct (eski adıyla Ingenico Direct) satıcı hesabı. Test ve canlı hesaplar ayrıdır ve farklı kimlik bilgilerine sahiptir. Her hesap için Merchant ID (PSPID'niz), bir API Key ID ve buna ait Secret API Key ile bir webhook anahtarı ve buna ait secret gerekir. Hepsi Worldline Merchant Portal'ında oluşturulur (bkz. «Configuration»).

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

Kurulum

1. WordPress'te Plugins > Add New > Upload Plugin yolunu izleyin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_worldline_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 > Worldline (Ingenico) > Manage yolunu izleyin ya da Eklentiler 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. Test kimlik bilgilerini girin, ayarları kaydedin ve Test credentials düğmesine tıklayın.

6. Test hesabının Merchant Portal'ına webhook URL'sini ekleyin ve webhook anahtarını ile secret'ını girin (bkz. «Configuration»).

7. Enable/Disable seçeneğini açın ve bir test ödemesi yapın. Ardından canlı kimlik bilgilerini girin, canlı hesabınızda webhook kurulumunu tekrarlayın, Live credentials düğmesine tıklayın ve Test Mode seçeneğinin işaretini kaldırın.

Configuration

Tüm ayarlar tek bir sayfadadır: WooCommerce > Settings > Payments > Worldline (Ingenico). Ödeme yöntemleri listesinde, geçerli modda bir Merchant ID, bir API Key ID ve bir Secret API Key olana kadar Worldline kurulum gerektiren olarak işaretlenir. Ayarlar sayfasında, kullanılmayan modun kimlik bilgisi alanları soluk gösterilir.

General

Enable/Disable: Enable Worldline 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: Worldline.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via Worldline.

Worldline Direct API

Kimlik bilgilerini hem test hesabının hem de canlı hesabın Worldline Merchant Portal'ından alın. PSPID'niz Merchant ID'dir. Developer > Payment API API Key ID ve Secret API Key'i oluşturur; Developer > Webhooks ise webhook anahtarını ve secret'ını. Bu bölümde iki portala ve Worldline dokümantasyonuna bağlantılar bulunur.

Test Mode: Enable test mode (pre-production environment, no real money) hem API uç noktasını hem de kimlik bilgilerini değiştirir. Test modu ön üretim ortamını ve test kimlik bilgilerini, canlı mod ise üretim ortamını ve canlı kimlik bilgilerini kullanır. Varsayılan: açık. Gerçek ödeme almak için işaretini kaldırın. Test modu açıkken müşteriler ödeme yönteminin altında Test mode — no real money is charged. ifadesini görür.

Test hesabı (ön üretim)

Test Merchant ID (PSPID): test hesabınızın PSPID'si.

Test API Key ID: test hesabının Developer > Payment API bölümünde oluşturulan API Key ID.

Test Secret API Key: bu API Key ID'ye ait Secret API Key.

Test Webhook Key ID: isteğe bağlı. Ayarlandığında yalnızca bu anahtarla gönderilen webhook'lar kabul edilir.

Test Webhook Secret: test hesabının webhook secret'ı. Her webhook'un imzasını doğrulamak için kullanılır.

Canlı hesap (üretim)

Live Merchant ID (PSPID): canlı hesabınızın PSPID'si.

Live API Key ID: canlı hesabın Developer > Payment API bölümünde oluşturulan API Key ID.

Live Secret API Key: bu API Key ID'ye ait Secret API Key.

Live Webhook Key ID: isteğe bağlı. Ayarlandığında yalnızca bu anahtarla gönderilen webhook'lar kabul edilir.

Live Webhook Secret: canlı hesabın webhook secret'ı.

Kimlik bilgilerini kontrol et

Test credentials ve Live credentials düğmeleri, her hesabın kayıtlı kimlik bilgilerini Worldline'a yapılan bir test çağrısıyla kontrol eder. Önce değişikliklerinizi kaydedin. Yanıt düğmelerin yanında görünür; örneğin Test credentials: connection successful., API credentials are not configured. ya da Worldline'ın döndürdüğü hata.

Webhooks

Webhook, müşteri mağazaya geri dönmese bile mağazanıza ödemeler hakkında bilgi verir; örneğin tarayıcıyı kapattıktan sonra ya da bir ödeme daha sonra onaylandığında. Test hesabının Merchant Portal'ında Developer > Webhooks bölümünü açın ve ayarların bu bölümünde gösterilen uç nokta URL'sini ekleyin. URL şu biçimdedir: https://your-site/wc-api/wlg_worldline_webhook/. URL'yi ayarların gösterdiği gibi birebir kopyalayın: yönlendirme yapmadan yanıt vermelidir, bu yüzden dil önekleri ile zorunlu www veya https yönlendirmelerini kontrol edin. Ardından webhook anahtar kimliğini ve secret'ını Test Webhook Key ID ve Test Webhook Secret alanlarına girin. Canlı hesap için aynısını canlı alanlarla yapın.

Eklenti, Worldline'ın uç nokta doğrulama isteğine otomatik olarak yanıt verir. Ödeme olaylarını (ödeme durumu değişiklikleri) ve iade olaylarını (iade durumu değişiklikleri) işler. Diğer olaylar kabul edilir ve yok sayılır. Geçerli imzası olmayan webhook'lar reddedilir. Bir webhook, secret'ı webhook'u imzalayan hesabın Merchant ID'sinden farklı bir Merchant ID'den geliyorsa da yok sayılır. Webhook olmadan bir sipariş, ancak müşteri ödemeden sonra mağazaya döndüğünde onaylanır.

Ödeme sayfası ve siparişler

Payment page template: Merchant Portal'a yüklenmiş barındırılan bir ödeme sayfası şablonunun (varyantının) isteğe bağlı adı; örneğin SimplifiedCustomPaymentPage. Worldline'ın varsayılan ödeme sayfasını kullanmak için boş bırakın.

Order Status After Payment: Worldline tahsil edilen ödemeyi onayladıktan sonraki sipariş durumu. Durum hemen ayarlanır; ikinci bir durum değişikliği gerekmez. Ödemeler her zaman doğrudan satış olarak (yetkilendirme ve tahsilat) talep edilir.

Logging: Enable debug logging tüm API isteklerini ve webhook'ları WooCommerce > Status > Logs altına, kaynak wcp_worldline_gateway olarak yazar. Hatalar ve uyarılar bu seçenek kapalıyken de her zaman kaydedilir. Anahtarlar, kart bilgileri ve kişisel veriler maskelenir. Varsayılan: kapalı.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. Eklentiyi devre dışı bırakmak hiçbir şeyi silmez. Siparişlerde saklanan ödeme verileri iadeler için gerektiğinden korunur. Varsayılan: kapalı.

1.0 sürümünden güncelleme yaparken eski tek kimlik bilgisi seti, mağazanın kullandığı moda göre test veya canlı alanlara taşınır.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Worldline) ve siparişi verir. Eklenti, sipariş tutarı için sipariş para biriminde bir Worldline barındırılan ödeme sayfası oluşturur ve müşteriyi Worldline ödeme sayfasına gönderir. Orada müşteri, kart, dijital cüzdan veya Worldline hesabınızda etkinleştirilmiş başka bir ödeme yöntemiyle öder. Fatura adı, adres, e-posta ve telefon Worldline'a iletilir; Worldline destekliyorsa ödeme sayfası mağazanızın dilinde açılır. Her ödeme denemesi, sipariş kimliği ve rastgele bir bölümden oluşan kendi referansını alır.

Ödemeden sonra müşteri mağazanıza geri döner. Eklenti dönüşü kaydedilen denemeye göre kontrol eder ve ödeme durumunu sunucu tarafında Worldline'dan okur. Sipariş, ancak Worldline onayladıktan sonra ödenmiş olarak işaretlenir: bu durum kontrolü veya imzalı bir webhook ile. Ardından müşteri sipariş alındı sayfasını görür.

Ödeme tamamlanmadıysa müşteri bir mesajla birlikte Pay for order sayfasına yönlendirilir:

Müşteri, ödenmemiş bir siparişi Pay for order sayfasından yeniden ödeyebilir. Önceki deneme bu arada ödendiyse müşteri doğrudan sipariş alındı sayfasına gider ve iki kez ücretlendirilmez. Önceki ödeme sayfası aynı tutar ve mod için hâlâ açıksa ve 30 dakikadan kısa süre önce oluşturulduysa müşteri oraya geri yönlendirilir.

Worldline ödemeyi başlatamazsa müşteri Payment error: Could not create checkout session. Please try again. mesajını görür ve başka bir ödeme yöntemi seçebilir. Neden, sipariş notlarına ve günlüğe eklenir. Geçerli modun kimlik bilgileri eksikse müşteri This payment method is not available at the moment. Please choose another payment method. mesajını görür.

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

Eklenti, tek seferlik ödemeleri Worldline sayfasında doğrudan satış olarak kabul eder. Kayıtlı kart veya tokenizasyon, abonelik, gömülü kart formu, WooCommerce'ten yetkilendirme ve ardından tahsilat veya iptal yapılan yalnızca yetkilendirme modu, ek ücret (surcharge) ve otomatik webhook kaydı yoktur.

Siparişler ve iadeler

Order statuses

Pending payment: Müşteri Worldline'a yönlendirildi ve henüz ödeme yapmadı ya da Worldline ödemeyi henüz onaylamadı. Bir not, barındırılan ödeme sayfası kimliğini, referansı ve modu (test veya canlı) gösterir.

Processing or Completed: Ödeme tahsil edildi. Durum Order Status After Payment ayarını izler. Sipariş notu tutarı, Worldline ödeme kimliğini ve onayın nasıl alındığını (imzalı webhook veya durum kontrolü) gösterir. Siparişin işlem kimliği, Worldline ödeme kimliğidir.

On hold, waiting for capture: Worldline ödemeyi yetkilendirilmiş ya da tahsilatı talep edilmiş olarak bildirir, ama henüz tahsil edilmemiştir. Sipariş notu bunu açıklar. Webhook tahsilatı onayladığında sipariş otomatik olarak ödenmiş olarak işaretlenir. Not ödemenin tahsil edilmediğini söylüyorsa, Worldline Merchant Portal'ında tahsil edin.

On hold, held for manual review: Ödeme siparişle eşleşmiyor; örneğin tutar veya para birimi farklı (ödeme başladıktan sonra sipariş düzenlendi) ya da ödeme başka bir denemeye ait. Not, ödenen tutarı, sipariş toplamını ve referansı gösterir. Siparişi kontrol edin ve yerine getirin ya da ödemeyi iade edin.

Failed: Worldline, son denemenin ödemesini reddetti veya iptal etti ya da müşteri seçilen ödeme yöntemine uygun değildi.

Cancelled: Sipariş sizin tarafınızdan ya da WooCommerce stok tutma zaman aşımı nedeniyle iptal edildi. İptal edilmiş veya iade edilmiş bir siparişe ödeme gelirse sipariş yeniden açılmaz. Bir not sizden ödemeyi Worldline Merchant Portal'ında iade etmenizi veya iptal etmenizi ya da siparişi elle geri yüklemenizi ister. Geri dönen müşteri Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. mesajını görür.

Zaten ödenmiş bir siparişe ikinci bir ödeme gelirse sipariş yeniden değiştirilmez. Bir not, ikinci ödemeyi Worldline Merchant Portal'ında iade etmenizi ister.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Worldline (Ingenico) düğmesine tıklayın. Tam ve kısmi iadeler desteklenir. Ödemenin tahsil edilmiş olması gerekir. İade her zaman orijinal ödemenin ortamına (test veya canlı) o hesabın kimlik bilgileriyle gönderilir; bu nedenle bunların ayarlanmış olması gerekir. Zaman aşımından sonra yeniden denenen bir iade iki kez çalıştırılmaz. Worldline iadeyi reddederse WooCommerce hatayı gösterir ve hiçbir iade kaydedilmez. Kabul edilen bir iade, Worldline iade kimliği ve durumuyla birlikte sipariş notlarına eklenir.

Worldline'dan gelen iade durumu değişiklikleri webhook ile ulaşır ve sipariş notlarına eklenir. Merchant Portal'da yapılan iadeler otomatik olarak WooCommerce iadesi olarak kaydedilmez. Gerekirse Refund via Worldline (Ingenico) kullanmadan WooCommerce'te 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 > Worldline (Ingenico) sayfasının üst kısmındadır. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blok durumu gösterir; örneğin lisansın hangi tarihe kadar aktif olduğunu ve alan adınızı. Durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu siteden kaldırmak için Remove key düğmesini kullanın. Manage licenses and domains in your account bağlantısı vibefox.net hesabınızı açar.

Bir anahtar yalnızca bir alan adında çalışır. Anahtarı bir siteden kaldırmak, o sitenin alan adı hakkını serbest bırakmaz. Bunu vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan Worldline müşterilere ödeme sayfasında 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) işaretiyle görmeye devam eder. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler onaylanmaya devam eder ve iadeler çalışır.

Bir lisansın süresi dolduğunda eklenti çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum arka planda otomatik olarak yeniden kontrol edilir.

Sorun giderme

Worldline ö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 bir Merchant ID, bir API Key ID ve bir Secret API Key bulunduğunu kontrol edin: test modunda test alanları, canlı modda canlı alanlar. Ödeme listesi, bunlar eksikse yöntemi kurulum gerektiren olarak işaretler.

Ödeme geçti, ancak sipariş Pending payment durumunda kalıyor: Webhook çalışmıyor. Kullandığınız hesabın (test veya canlı) Merchant Portal'ında uç noktanın var olduğunu ve URL'sinin ayarlarda gösterilenle birebir aynı olduğunu, yönlendirme içermediğini kontrol edin. O hesabın webhook secret'ının ilgili alanda (Test Webhook Secret veya Live Webhook Secret) olduğunu ve Webhook Key ID alanının boş olduğunu ya da anahtarla eşleştiğini kontrol edin. Müşteri ödemeden sonra mağazaya döndüğünde sipariş yine de onaylanır.

Webhook şu yanıtı veriyor: Webhook secret not configured: Hiçbir webhook secret'ı ayarlanmamış. Ayarlarda webhook secret'ını girin. Worldline webhook'u yeniden dener.

Webhook şu yanıtı veriyor: Invalid signature: Webhook secret'ı başka bir hesaba veya başka bir anahtara ait ya da Webhook Key ID alanı webhook'u gönderen anahtarla eşleşmiyor.

Webhook şu yanıtı veriyor: Missing signature, Empty body veya Invalid JSON: İstek Worldline'dan beklenen biçimde gelmedi ya da bir proxy veya yönlendirme onu değiştirdi. URL'nin yönlendirme yapmadan yanıt verdiğini kontrol edin.

Webhook şu yanıtı veriyor: Ignored: Webhook, o modun ayarlarındaki Merchant ID'den farklı bir Merchant ID'den geldi. Test Merchant ID (PSPID) veya Live Merchant ID (PSPID) alanını kontrol edin.

Webhook şu yanıtı veriyor: Retry later: Sipariş, aynı anda başka bir istek tarafından güncelleniyordu. Worldline webhook'u yeniden dener.

Test credentials veya Live credentials bir hata gösteriyor: Önce ayarları kaydedin, ardından Merchant ID, API Key ID ve Secret API Key'in aynı hesaptan geldiğini ve test değerlerinin test alanlarında, canlı değerlerin canlı alanlarında olduğunu kontrol edin.

Müşteri sipariş verirken bir hata görüyor: Sipariş notlarını ya da WooCommerce > Status > Logs bölümünü, kaynak wcp_worldline_gateway olarak açın. Hata ayıklama günlüğü kapalı olsa bile hatalar kaydedilir. İsteklerin tüm ayrıntıları için Logging seçeneğini açın ve yeniden deneyin.

Test ödemeleri canlı bir siparişi onaylamıyor: Test ve canlı ayrı tutulur. Test secret'ı ile imzalanmış bir webhook hiçbir zaman canlı bir ödeme denemesini onaylamaz; tersi de geçerlidir. Test Mode seçeneğini istediğiniz moda getirin ve o hesabın kimlik bilgilerini ve webhook'unu kullanın.

Ödemeden sonra sipariş On hold durumunda: Sipariş notunu okuyun. Ya Worldline tahsilatı henüz onaylamadı (webhook siparişi tamamlar) ya da ödenen tutar veya para birimi siparişten farklıydı.

İade ortamla ilgili bir mesajla başarısız oluyor: Ödeme test veya canlı ortamda yapıldı ve o ortamın kimlik bilgileri ayarlanmamış. Bunları girin ve yeniden deneyin.

Geliştiriciler: wlg_hosted_checkout_data filtresi barındırılan ödeme sayfası isteğini değiştirir; örneğin gösterilen ödeme yöntemlerini sınırlamak için. wlg_gateway_icon ise ödeme yöntemi simgesini değiştirir.

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

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Kaldırmak için eklentiyi Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ağ geçidi ayarları ve günlükler yalnızca Delete Data açıksa kaldırılır. Aksi halde sonraki bir yeniden kurulum için saklanırlar. Siparişlerde saklanan Worldline ödeme verileri, iadeler için gerektiğinden her zaman korunur. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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