VibeFox Adyen for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ile 9.x arası.

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

Adyen hesabı: kullandığınız her ortam (test ve canlı) için Adyen satıcı hesabı adınıza, bir API anahtarına ve bir HMAC anahtarına ihtiyacınız vardır; canlı ödemeler için ayrıca canlı URL önekine. API anahtarı, Checkout webservice ve Merchant PAL webservice rollerine sahip bir API kimlik bilgisine aittir. HMAC anahtarı, Standard webhook için oluşturulur (bkz. Yapılandırma). Test Müşteri Alanı ca-test.adyen.com, canlı olan ca-live.adyen.com adresindedir. Test ve canlı anahtarlar ayrıdır. Ödeme sayfası Adyen tarafından barındırıldığı için istemci anahtarı gerekmez.

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 (back office) 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 Adyen Gateway modülünü bulup Configure düğmesine tıklayın.

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

4. Satıcı hesabınızı, test API anahtarını ve test HMAC anahtarını girin; daha sonra canlı API anahtarını, canlı HMAC anahtarını ve canlı URL önekini girin.

5. Adyen Müşteri Alanında (test ve canlı) bu modülün Webhook bölümünde gösterilen URL ile bir Standard webhook ekleyin (bkz. Yapılandırma).

6. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Test mode açıkken bir ödeme deneyin, ardından kapatın.

Kurulumda modül Adyen payment on hold sipariş durumunu oluşturur. PrestaShop, o anda etkin olan para birimleri, ülkeler ve müşteri gruplarıyla yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünde kontrol edin ve değiştirin; daha sonra eklediğiniz ülkelerin orada işaretlenmesi gerekir.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Geçerli modun ayarları eksik olduğu sürece sayfa, Adyen is hidden at checkout until the test settings are complete (veya canlı ayarlar) mesajını gösterir ve eksik olanları listeler: Merchant account, API anahtarı, HMAC anahtarı ve canlı modda Live URL prefix. Test mode açıkken sayfa Test mode is on: payment links and refunds go to the Adyen test environment, no real money. mesajını gösterir. Kaydederken, onaltılık olmayan bir HMAC anahtarı ile harf, rakam ve tire dışında karakter içeren bir canlı URL öneki kaydedilmez: bir uyarı alanı belirtir ve önceki değer korunur.

Adyen

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

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

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

Adyen hesabı

API anahtarları Adyen Müşteri Alanında, Developers > API credentials altında oluşturulur. İki anahtar setini de doldurun; Test mode anahtarı hangisinin kullanılacağını belirler.

Test mode: Adyen test ortamını kullanır (gerçek para yok). Açıkken ödeme bağlantıları ve iadeler, test API anahtarıyla checkout-test.adyen.com adresine gider. Varsayılan: açık. Gerçek ödemeleri kabul etmek için kapatın. Açık olduğu sürece müşteriler ödeme yönteminin altında Test mode: no real payment is taken. mesajını görür.

Merchant account: Adyen satıcı hesabınızın adı (şirket hesabı değil), örneğin MyShopECOM. Genellikle test ve canlı Müşteri Alanlarında aynıdır.

Test kimlik bilgileri

Test mode açıkken kullanılır.

Test API key: test Müşteri Alanından: Developers > API credentials > kimlik bilginiz > API key.

Test HMAC key: test Müşteri Alanından: Developers > Webhooks > Standard webhook'unuz > HMAC key (onaltılık). Zorunlu: geçerli imzası olmayan webhook'lar reddedilir.

Canlı kimlik bilgileri

Test mode kapalıyken kullanılır.

Live API key: canlı Müşteri Alanından: Developers > API credentials > kimlik bilginiz > API key.

Live HMAC key: canlı Müşteri Alanından: Developers > Webhooks > Standard webhook'unuz > HMAC key (onaltılık).

Live URL prefix: canlı Müşteri Alanından: Developers > API URLs, örneğin https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com adresinden 1797a841fbb37ca7-AdyenDemo. Tüm URL'yi yapıştırabilirsiniz; kaydederken önek bundan alınır.

Kayıtlı API anahtarları ve HMAC anahtarları bir daha gösterilmez. Alan boş kalır ve ipucu Saved — leave empty to keep it. ile biter. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Clear saved secrets: bir anahtarı işaretleyin ve kaldırmak için Save düğmesine tıklayın. Boş alan kayıtlı değeri korur.

Webhook

Siparişler yalnızca Adyen webhook'ları ile oluşturulur. Müşteri Alanında (test ve canlı) Developers > Webhooks bölümüne gidin ve bu bölümde Webhook URL altında gösterilen URL ile bir Standard webhook ekleyin. Dostça URL'lerle şu biçimde görünür: https://your-shop/module/wcp_adyen_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. URL'yi ayarların gösterdiği gibi birebir kopyalayın, çünkü Adyen yönlendirmeleri takip etmez. JSON yöntemini seçin, Generate HMAC key seçeneğini etkinleştirin ve anahtarı Test HMAC key veya Live HMAC key alanına kopyalayın.

Her bildirimin ortamı HMAC anahtarını seçer; bir bildirim yalnızca aynı ortamda ve aynı satıcı hesabıyla oluşturulmuş bir ödeme bağlantısına uygulanır. Test bildirimi hiçbir zaman gerçek bir ödemeyi onaylamaz. Geçerli imzası olmayan webhook'lar HTTP 401 ile reddedilir ve Adyen bunları daha sonra yeniden dener. Webhook olmadan sipariş oluşturulmaz.

Modül şu olayları işler:

Diğer olaylar sipariş notlarına eklenir. Bu mağazanın bir sepetine ait olmayan bildirimler, örneğin Müşteri Alanındaki test düğmesi, kabul edilir ve yok sayılır. Webhook, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez.

Gelişmiş

Order status after payment: başarılı bir AUTHORISATION webhook'unun ayarladığı sipariş durumu.

Tutar veya para birimi uyuşmazlıkları ve başarısız tahsilatlar her zaman Adyen payment on hold durumuna gider.

Debug log: API çağrılarını ve webhook olaylarını modül klasöründeki logs/adyg_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar, anahtar kapalı olsa bile her zaman kaydedilir. Günlükler hiçbir zaman API veya HMAC anahtarlarını ya da alışveriş yapanların kişisel verilerini içermez. 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 modül ayarları, Adyen ödeme kayıtları (PSP referansları, webhook olayları, iadeler) ve günlükler silinir. Adyen payment on hold sipariş durumu ve siparişler kalır. Varsayılan: kapalı.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Adyen) ve You will be redirected to Adyen to complete the payment securely. notunu görür. Onaylandıktan sonra modül, sepet toplamı için sepet para biriminde bir Adyen ödeme bağlantısı oluşturur ve müşteriyi Adyen'in ödeme sayfasına gönderir. Orada müşteri, Adyen hesabınızda etkin olan herhangi bir yöntemle öder. Müşterinin e-posta adresi, adı ve fatura ülkesi ile mağazanın dili Adyen'e iletilir; ödeme Cart # ve sepet numarası olarak görünür. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza geri döner. Bu dönüş tek başına sipariş oluşturmaz veya ödeme almaz: sipariş yalnızca Adyen imzalı AUTHORISATION webhook'u ile onayladığında ve tutar ile para birimi sepetle eşleştiğinde ödenmiş olarak işaretlenir. Webhook zaten geldiyse müşteri standart sipariş onay sayfasını görür: Your payment with Adyen has been received. (veya beklemedeki bir sipariş için Your payment with Adyen has been received and is being reviewed by the store.). Bundan önce Adyen ödemeyi iptal ettiyse sayfa Your Adyen payment was not completed. Please contact us about this order. mesajını gösterir. Webhook henüz gelmediyse Payment confirmation sayfası, ödemeyi tamamlamamış müşteri için Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. metnini, Check again ve Back to checkout düğmeleriyle birlikte gösterir.

Ödeme reddedilirse sipariş oluşturulmaz ve müşteri yeniden deneyebilir. Müşteri aynı sepet için yeni bir ödeme başlattığında önceki ödeme bağlantısının süresi dolar, bu nedenle o bağlantı üzerinden de ödeme yapılamaz. Sepetin zaten bir siparişi varsa müşteri yeni bir ödeme yerine o siparişin onay sayfasına gider.

Ödeme bağlantısı oluşturulamazsa müşteri ödeme sayfasında kalır ve Payment could not be initiated. Please try again or choose another payment method. mesajını görür. Neden günlüğe yazılır. Ayarlar eksikse mesaj Payment gateway is not configured properly. Please contact the store administrator. olur.

Geliştiriciler, ödeme bağlantısı isteğini actionAdygPaymentLinkRequest hook'u ile değiştirebilir.

Modülde abonelik veya yinelenen ödeme, kayıtlı kart, sitede kart alanı (Drop-in veya Components), PrestaShop'ta tahsilat veya iptal düğmesi ve webhook'lar için temel kimlik doğrulama bulunmaz.

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri Adyen'e yönlendirildi ve ödeme yapmadı, ödeme reddedildi veya Adyen henüz ödemeyi onaylamadı. Yalnızca sepet vardır.

Payment accepted, Delivered or Adyen payment on hold: ödeme yetkilendirildi. Durum Order status after payment ayarını izler. Ödeme, Adyen PSP referansı işlem kimliği olarak kaydedilir; bir not tutarı, PSP referansını ve ödeme yöntemini gösterir.

Adyen payment on hold after payment: Adyen, sepet toplamından farklı bir tutar veya para birimi onayladı (örneğin ödeme başladıktan sonra sepet değiştirildi), bir tahsilat başarısız oldu veya ödeme, sipariş iptal edildikten sonra geldi. Not bunu açıklar. Ödemeyi Müşteri Alanında kontrol edin, ardından siparişi yerine getirin veya ödemeyi iade edin.

Canceled: bu siparişin ödemesi Adyen'de iptal edildi.

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

Zaten ödenmiş bir siparişe, örneğin eski bir ödeme bağlantısından ikinci bir başarılı ödeme gelirse sipariş değişmez. Bir not, Müşteri Alanında çift tahsilat olup olmadığını kontrol etmenizi ve gerekirse orada iade etmenizi ister.

Adyen ödeme bloğu

Sipariş sayfası; PSP referansı, ödeme bağlantısı, satıcı hesabı ve ortam, ödeme durumu, ödenen ve iade edilen tutar, test ödemeleri için bir Test mode rozeti, iade geçmişi ve Adyen notes bölümünü gösteren bir Adyen payment bloğu içerir. Adyen notes, modülün siparişe eklediği notlardır (ödeme yetkilendirildi, tutar uyuşmazlığı, çift ödeme, tahsilat, iptal, iade sonuçları) ve en yeniden en eskiye sıralanır. Bu notlar siparişin özel mesajlarıdır; PrestaShop 8.2 ve 9 bunları sipariş sayfasının başka bir yerinde göstermez.

İadeler

Adyen payment bloğunda tutarı girin (henüz iade edilmeyen tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Adyen düğmesine tıklayın. Refund this amount through Adyen? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler desteklenir. Siparişleri düzenleme yetkisine ihtiyacınız vardır. İadeler, Adyen'in yetkilendirdiği tutar ve para birimde yapılır; bu nedenle bir tutar veya para birimi uyuşmazlığından sonra, sipariş toplamına değil müşterinin gerçekten ödediği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı ortama ve satıcı hesabına gönderilir; bu nedenle o ortamın API anahtarı ayarlanmış olmalıdır. Adyen isteği kabul etmezse blok hatayı gösterir ve hiçbir iade kaydedilmez.

Adyen iadeleri eşzamansız işler: istek, iade geçmişine ve received durumuyla notlara eklenir ve son sonuç REFUND veya REFUND_FAILED webhook'u ile gelir. Başarısız bir iade artık iade edilmiş sayılmaz. Gönderilen iadeler ödenen tutara ulaştığında sipariş Refunded olur. Kısmi bir iade durumu değiştirmez. Adyen'de manuel tahsilat ile yalnızca tahsil edilmiş ödemeler iade edilebilir.

Modül kredi notu oluşturmaz. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Adyen üzerinden para göndermez. Adyen Müşteri Alanında yapılan iadeler webhook ile gelir ve notlara eklenir. Sipariş durumu ve kredi notları otomatik olarak değiştirilmez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Adyen Gateway lisans bloğu, Modules > Module Manager > VibeFox Adyen Gateway > Configure sayfasında ayarların üstündeki 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 tarih ve alan adınız) gösterir ve şu düğmeleri içerir: 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-adyen 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 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 belirtir, ö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 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 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 serbest bırakın.

Etkin bir anahtar olmadan Adyen, ö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 sizden de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ancak ödeme sayfasında test edemezsiniz. Modules > Module Manager içinde Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Bir lisansın süresi dolduğunda modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Yönetim panelinde çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün günde bir kez, sonrasında haftada bir kez. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

Adyen ö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 ayarlarının tamamlandığını kontrol edin: Merchant account, o modun API anahtarı ve HMAC anahtarı ile canlı modda Live URL prefix. Ayarlar sayfası eksikleri listeler. 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 gerçekleşti ama sipariş oluşturulmadı: webhook çalışmıyor. Kullandığınız ortamın (test veya canlı) Müşteri Alanında Standard webhook'un var olduğunu, URL'sinin Webhook URL altında gösterilenle birebir aynı olduğunu ve yönteminin JSON olduğunu kontrol edin. Bu webhook'un HMAC anahtarının doğru alanda (Test HMAC key veya Live HMAC key) olduğunu kontrol edin. Geçersiz veya eksik bir HMAC anahtarında modül HTTP 401 yanıtı verir ve Adyen teslimatı daha sonra yeniden dener; bu nedenle anahtar düzeltildiğinde sipariş otomatik oluşturulur. Günlükte Webhook rejected: invalid HMAC signature veya HMAC anahtarının yapılandırılmadığı görünür.

Webhook [rejected] HMAC key not configured yanıtı veriyor: bildirimin ortamının HMAC anahtarı boş. Ayarlara yapıştırın.

Webhook [rejected] busy, retry later yanıtı veriyor: sepet aynı anda başka bir teslimat tarafından işleniyordu veya sipariş oluşturulamadı (örneğin modül devre dışıysa). Adyen webhook'u otomatik olarak yeniden dener. Neden günlüktedir.

Webhook URL'si tarayıcıda [rejected] POST required in the browser gösteriyor: bu normaldir. URL yalnızca Adyen'den gelen bildirimleri kabul eder.

Kaydederken HMAC anahtarı uyarısı: alan, Müşteri Alanındaki onaltılık HMAC anahtarını içermelidir. Önceki değer korundu.

Müşteri Payment could not be initiated mesajını görüyor: modül sayfasındaki Log alanına bakın (hatalar her zaman kaydedilir). API anahtarını, satıcı hesabını ve canlı modda canlı URL önekini kontrol edin.

Ödemeden sonra sipariş Adyen payment on hold durumunda: siparişteki notu okuyun. Adyen'in onayladığı tutar veya para birimi sepetle eşleşmedi, bir tahsilat başarısız oldu veya ödeme bir iptalden sonra geldi. Ayrıca Order status after payment ayarınız da neden olabilir.

İade başarısız oluyor: siparişin, AUTHORISATION webhook'u ile gelen bir Adyen PSP referansı olmalıdır. Ödemenin yapıldığı ortamın kimlik bilgileri ayarlanmış olmalıdır; aksi halde blok, kimlik bilgilerinin yapılandırılmadığını gösterir. Manuel tahsilatla yalnızca tahsil edilmiş ödemeler iade edilebilir.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Adyen 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 modül ayarları, Adyen ödeme kayıtları (PSP referansları, webhook olayları, iadeler) ve günlükler silinir. Kapalıysa bunların tümü, daha sonra yeniden kurulum için saklanır; böylece daha önce ödenen siparişler yine iade edilebilir. Adyen payment on hold sipariş durumu her zaman kalır. Mevcut siparişler, ödeme notlarını ve işlem kimliklerini korur.

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