VibeFox Worldline for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

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

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. Yapılandırma).

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 Worldline Gateway öğesini bulup Configure düğmesine tıklayın.

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

4. Test kimlik bilgilerini girin, Save ve ardından Test credentials düğmesine tıklayın.

5. Test hesabının Merchant Portal'ında webhook URL'sini ekleyin ve webhook anahtarını ile secret'ını girin (bkz. Yapılandırma).

6. 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ğini kapatın.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Worldline capture ve Worldline payment on hold. PrestaShop, o anda aktif olan ülkeler için yeni bir ödeme modülünü etkinleştirir. Para birimlerini, ülkeleri ve müşteri gruplarını Payment > Preferences bölümünde kontrol edin ve daha sonra eklediğiniz ülkeleri orada işaretleyin.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Worldline 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, geçerli modun kimlik bilgileri (Merchant ID, API Key ID, Secret API Key) eksikse uyarır; çünkü bu durumda ödeme yöntemi ödeme sayfasında gizlenir. Test modu açıkken sayfa Test mode is on (pre-production environment): no real money is charged. mesajını gösterir.

Worldline (Ingenico)

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ı. Siparişte de ödeme yöntemi adı olarak saklanır. Varsayılan: Worldline. Zorunlu.

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

Worldline Direct API

Kimlik bilgilerini test ve canlı hesapları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ı oluşturur. Bu bölümde her iki portala ve Worldline dokümantasyonuna bağlantılar bulunur.

Test Mode: 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 kapatın. Test modu açıkken müşteriler ödeme yönteminin altında Test mode — no real money is charged. mesajını 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'ı.

Kayıtlı secret anahtarlar ve webhook secret'ları 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 secrets: bir secret'ı işaretleyip Save düğmesine tıklayarak kaldırın. Boş bir alan kayıtlı değeri korur.

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

Webhook'lar

Webhook, müşteri mağazaya geri dönmese bile ödemeler hakkında mağazanıza bilgi verir; örneğin tarayıcıyı kapattıktan sonra veya bir ödeme daha sonra onaylandığında. Merchant Portal'da test hesabının Developer > Webhooks bölümünü açın ve bu bölümde Endpoint URL altında gösterilen URL'yi ekleyin. Dostça URL'lerde şöyle görünür: https://your-shop/module/wcp_worldline_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. URL'yi ayarlarda gösterildiği gibi birebir kopyalayın: yönlendirme yapmadan yanıt vermelidir. Ardından webhook anahtar kimliğini ve secret'ını Test Webhook Key ID ve Test Webhook Secret alanlarına girin. Canlı hesapta da canlı alanlarla aynı işlemi yapın.

Modül, Worldline'ın uç nokta doğrulama isteğini otomatik olarak yanıtlar. Ö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 olay, ödemenin yapıldığı hesabın secret'ı ile imzalanmış olmalıdır; bu nedenle bir test webhook'u asla canlı bir ödemeyi onaylamaz. Ayrıca bir webhook, secret'ı onu imzalayan hesabın Merchant ID'sinden farklı bir Merchant ID'den gelirse yok sayılır. Webhook olmadan sipariş yalnızca müşteri ödemeden sonra mağazaya döndüğünde oluşturulur.

Ödeme sayfası ve siparişler

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

Order Status After Payment: Worldline tahsil edilen ödemeyi onayladıktan sonraki sipariş durumu. Ödemeler her zaman doğrudan satış olarak (yetkilendirme ve tahsilat) talep edilir.

Yetkilendirilmiş ödemeler Awaiting Worldline capture durumunda bekler. Tutar veya para birimi uyuşmazlıkları her zaman Worldline payment on hold durumuna gider.

Gelişmiş

Logging: tüm API isteklerini ve webhook'ları modül klasöründeki logs/wlg_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar ve uyarılar bu seçenek kapalıyken de her zaman kaydedilir. Anahtarlar, kart bilgileri ve kişisel veriler maskelenir. 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: açıkken modülü kaldırmak modül ayarlarını ve günlüğü siler. Worldline işlemleri ve iadeleri ile modülün sipariş durumları her zaman kalır; mevcut siparişler iadeler için bunlara ihtiyaç duyar. Varsayılan: kapalı.

Ödeme

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Worldline) ve onaylar. Modül, sepet tutarı için sepet para biriminde bir Worldline barındırılan ödeme sayfası oluşturur ve müşteriyi Worldline ödeme sayfasına yönlendirir. 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ı müşterinin dilinde açılır. Her ödeme denemesi, sepet kimliği ve rastgele bir bölümden oluşan kendi referansını alır. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza geri döner. Modül dönüşü kayıtlı denemeye göre kontrol eder ve ödeme durumunu sunucu tarafında Worldline'dan okur. Sipariş, yalnızca Worldline onayladıktan sonra ödenmiş olarak işaretlenir: bu durum kontrolü ile veya imzalı bir webhook ile. Sipariş daha sonra oluşturulur ve müşteri Your payment with Worldline has been received. mesajının yer aldığı standart sipariş onay sayfasını görür. Ödeme yetkilendirilmiş ama henüz tahsil edilmemişse sayfada Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. mesajı görünür. Böyle bir siparişin ödemesi daha sonra başarısız olursa sayfada Your Worldline payment was not completed. Please contact us about this order. mesajı görünür.

Ödeme tamamlanmadıysa sipariş oluşturulmaz, sepet korunur ve müşteri şu mesajla ödeme sayfasına geri döner:

Durum henüz kontrol edilemediyse Payment confirmation sayfasında We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. mesajı ve Check again ile Back to checkout düğmeleri görünür. Webhook geldiği anda siparişi oluşturur.

Müşteri aynı sepeti yeniden ödediğinde modül önce önceki denemeyi kontrol eder. Bu arada ödenmişse müşteri doğrudan sipariş onayı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şturulmuşsa müşteri oraya geri yönlendirilir.

Worldline ödemeyi başlatamazsa müşteri Payment error: Could not create checkout session. Please try again. mesajıyla ödeme sayfasında kalır. Neden günlüğe yazılır. 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.

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

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

Siparişler ve iadeler

Sipariş durumları

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

Payment accepted or Delivered: ödeme tahsil edildi. Durum, Order Status After Payment ayarını izler. Ödeme, Worldline ödeme kimliği işlem kimliği olarak kaydedilir; bir notta tutar, ödeme kimliği ve onay şekli (imzalı webhook veya durum kontrolü) gösterilir.

Awaiting Worldline capture: Worldline ödemeyi yetkilendirilmiş veya tahsilat talep edilmiş olarak bildirdi, ancak henüz tahsil edilmedi. Henüz bir ödeme kaydedilmedi. Webhook tahsilatı onayladığında sipariş ödenmiş duruma geçer. Notta ödemenin tahsil edilmediği yazıyorsa Worldline Merchant Portal'ında tahsil edin.

Worldline payment on hold: ödeme sepetle eşleşmiyor; örneğin tutar veya para birimi farklı (ödeme başladıktan sonra sepet değiştirildi) ya da ödeme başka bir denemeye ait. Notta ödenen tutar, sipariş toplamı ve referans gösterilir. Siparişi kontrol edip işleyin ya da ödemeyi iade edin.

Payment error: Worldline, tahsilat bekleyen bir siparişin ödemesini reddetti veya iptal etti.

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

İptal edilmiş veya iade edilmiş bir sipariş için ödeme gelirse sipariş yeniden açılmaz. Bir notta, ödemeyi Worldline Merchant Portal'ında iade etmeniz ya da iptal etmeniz veya siparişi elle geri yüklemeniz istenir. 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ş için ikinci bir ödeme gelirse sipariş değişmez. Bir notta, ikinci ödemeyi Worldline Merchant Portal'ında iade etmeniz istenir.

Worldline ödeme bloğu

Sipariş sayfasında ödeme kimliği, satıcı referansı, barındırılan ödeme sayfası, deneme durumu, tahsil edilen ve iade edilen tutar, test ödemeleri için bir Test environment rozeti, iade geçmişi ve siparişin Payment notes bölümünü içeren bir Worldline payment bloğu gösterilir.

İadeler

Worldline payment bloğuna tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Worldline düğmesine tıklayın. Refund this amount through Worldline? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Ödemenin tahsil edilmiş olması gerekir. Siparişleri düzenleme yetkisine sahip olmanız gerekir; modül sayfalarına erişim gerekmez. İadeler, Worldline'ın tahsil ettiği tutar ve para biriminde yapılır; bu nedenle tutar veya para birimi uyuşmazlığından sonra sipariş toplamına değil, müşterinin gerçekten ödediği tutara kadar iade yapabilirsiniz. İade her zaman orijinal ödemenin ortamına (test veya canlı) o hesabın kimlik bilgileriyle gönderilir; bu nedenle bu bilgilerin girilmiş olması gerekir. Zaman aşımından sonra yeniden denenen bir iade iki kez çalıştırılmaz ve bir siparişte aynı anda yalnızca bir iade çalışır. Worldline iadeyi reddederse blok hatayı gösterir ve hiçbir iade kaydedilmez. Kabul edilen bir iade, Worldline iade kimliği ve durumuyla birlikte iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez.

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

Worldline'dan gelen iade durumu değişiklikleri webhook ile gelir, iade geçmişini günceller ve notlara eklenir. Merchant Portal'da yapılan iadeler sipariş durumunu değiştirmez ve kredi notu oluşturmaz. Gerekirse bunları elle güncelleyin.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Worldline Gateway lisans bloğu, Modules > Module Manager > VibeFox Worldline Gateway > Configure sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bundan sonra blok, anahtarı maskeli olarak, durumu (örneğin lisansın geçerli olduğu son tarih 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-worldline 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 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 son bilinen 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 lisans anahtarı olmadan Worldline, ö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, back office'e giriş yaptığınızı bilmez; bu yüzden ödeme yöntemi sizden 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 çıkar. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler onaylanmaya ve iadeler çalışmaya devam eder.

Bir lisans sona erdiğinde 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 job gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

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 modun bir Merchant ID, API Key ID ve Secret API Key'e sahip olduğunu kontrol edin: test modunda test alanlarını, canlı modda canlı alanları. Eksik olduklarında ayarlar sayfası uyarı gösterir. 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.

Ödeme yapıldı ama sipariş oluşturulmadı: webhook çalışmıyor. Kullandığınız hesabın (test veya canlı) Merchant Portal'ında uç noktanın var olduğunu ve URL'sinin Endpoint URL altında gösterilenle birebir aynı olduğunu, yönlendirme içermediğini kontrol edin. O hesabın webhook secret'ının doğru alanda (Test Webhook Secret veya Live Webhook Secret) olduğunu ve webhook anahtar kimliği alanının boş olduğunu ya da anahtarla eşleştiğini kontrol edin. Müşteri ödemeden sonra mağazaya döndüğünde de sipariş oluşturulur.

Webhook «Webhook secret not configured» yanıtı veriyorsa: hiçbir webhook secret'ı ayarlanmamış. Ayarlara webhook secret'ını girin. Worldline webhook'u yeniden dener.

Webhook «Invalid signature» yanıtı veriyorsa: webhook secret'ı başka bir hesaba veya başka bir anahtara ait ya da webhook anahtar kimliği, webhook'u gönderen anahtarla eşleşmiyor. Test ve canlı secret'ların yer değiştirmediğini kontrol edin.

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

Webhook «Ignored» yanıtı veriyorsa: webhook, o modun ayarlarındakinden farklı bir Merchant ID'den geldi. Test Merchant ID (PSPID) veya Live Merchant ID (PSPID) alanını kontrol edin.

Webhook «Retry later» yanıtı veriyorsa: sipariş aynı anda başka bir istekle onaylanıyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Worldline webhook'u yeniden dener. Nedeni görmek için Log alanına bakın.

Webhook URL'si tarayıcıda Method not allowed gösteriyorsa: bu normaldir. URL yalnızca Worldline'dan gelen isteklerini kabul eder.

Test credentials veya Live credentials hata gösteriyorsa: ö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 Worldline'ı seçerken bir hata görüyor: modül sayfasındaki Log alanına bakın. Logging kapalı olsa bile hatalar kaydedilir. İsteklerin tüm ayrıntılarını görmek için Logging seçeneğini açın ve tekrar deneyin.

Test ödemeleri canlı bir ödemeyi onaylamıyor: test ve canlı birbirinden ayrıdır. Test Mode seçeneğini istediğiniz moda getirin ve o hesabın kimlik bilgilerini ve webhook'unu kullanın.

Ödemeden sonra sipariş Worldline payment on hold veya Awaiting Worldline capture durumunda: Worldline payment bloğundaki notları okuyun (bkz. Sipariş durumları). Ya Worldline tahsilatı henüz onaylamadı (webhook siparişi tamamlar) ya da ödenen tutar veya para birimi sepetten 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 girilmemiş. Bunları girin ve tekrar deneyin.

Geliştiriciler: actionWlgHostedCheckoutData hook'u, barındırılan ödeme isteğini gönderilmeden önce değiştirir; örneğin gösterilen ödeme yöntemlerini sınırlamak için.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Worldline 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 açıksa modül ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Worldline işlemleri ve iadeleri ile Awaiting Worldline capture ve Worldline 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.

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