VibeFox Adyen for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

Adyen hesabı: kullandığınız her ortam (test ve canlı) için bir API anahtarına ve bir HMAC anahtarına ihtiyacınız var; canlı ödemeler için ayrıca canlı URL önekine ihtiyacınız var. API anahtarı, Checkout webservice ve Merchant PAL webservice rollerine sahip bir API kimlik bilgisine aittir. HMAC anahtarı, Standard webhook için üretilir (bkz. Yapılandırma). Test Customer Area adresi ca-test.adyen.com, canlı olanı ca-live.adyen.com'dur. Test ve canlı anahtarlar ayrıdır.

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

Kurulum

1. WordPress'te Plugins > Add New > Upload Plugin yolunu izleyin, eklenti ZIP dosyasını seçin ve Install Now düğmesine tıklayın. Ayrıca wcp_adyen_gateway klasörünü FTP ile /wp-content/plugins/ dizinine de yükleyebilirsiniz.

2. Activate düğmesine tıklayın.

3. Ayarları açın: WooCommerce > Settings > Payments > Adyen > Manage yolunu izleyin veya Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

4. Sayfanın üstündeki lisans bölümüne VibeFox lisans anahtarınızı girin ve Activate düğmesine tıklayın.

5. 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.

6. Adyen Customer Area'da (test ve canlı için) eklenti ayarlarında gösterilen URL ile bir Standard webhook ekleyin (bkz. Yapılandırma).

7. Enable/Disable seçeneğini açın. Test mode açıkken bir ödeme deneyin, ardından işaretini kaldırın.

Yapılandırma

Tüm ayarlar tek bir sayfada: WooCommerce > Settings > Payments > Adyen. Geçerli modun ayarları eksik olduğu sürece sayfa Adyen is hidden at checkout until the test settings are complete (veya canlı ayarlar) uyarısını gösterir ve eksik olanları listeler: Merchant account, API anahtarı, HMAC anahtarı ve canlı modda Live URL prefix. Kaydettiğinizde, onaltılık (hexadecimal) olmayan bir HMAC anahtarı ile harf, rakam ve tire dışında karakter içeren bir canlı URL öneki hata ile reddedilir ve önceki değer korunur.

Genel

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öntemi adı. Varsayılan: Adyen.

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

Adyen hesabı

API anahtarları Adyen Customer Area'da Developers > API credentials altında oluşturulur. İki anahtar grubunu da doldurun; Test mode seçeneği hangisinin kullanılacağını belirler.

Test mode: Use the Adyen test environment (no real money). Açıkken ödeme bağlantıları ve iadeler, test API anahtarıyla checkout-test.adyen.com adresine gönderilir. Varsayılan: açık. Gerçek ödeme almak için işaretini kaldırın.

Merchant account: Adyen satıcı hesabınızın adı (şirket hesabı değil), örneğin MyShopECOM. Genellikle test ve canlı Customer Area'da aynıdır.

Test kimlik bilgileri

Test mode etkinken kullanılır.

Test API key: test Customer Area'dan: Developers > API credentials > kimlik bilginiz > API key.

Test HMAC key: test Customer Area'dan: Developers > Webhooks > Standard webhook'unuz > HMAC key (onaltılık). Zorunludur: geçerli imzası olmayan webhook'lar reddedilir.

Canlı kimlik bilgileri

Test mode kapalıyken kullanılır.

Live API key: canlı Customer Area'dan: Developers > API credentials > kimlik bilginiz > API key.

Live HMAC key: canlı Customer Area'dan: Developers > Webhooks > Standard webhook'unuz > HMAC key (onaltılık).

Live URL prefix: canlı Customer Area'dan: Developers > API URLs; örneğin https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com adresi için önek 1797a841fbb37ca7-AdyenDemo. Tüm URL'yi yapıştırabilirsiniz; kaydederken önek ondan alınır.

Webhook

Siparişler yalnızca Adyen webhook'ları ile ödenmiş olarak işaretlenir. Customer Area'da (test ve canlı için) Developers > Webhooks bölümüne gidin ve eklenti ayarlarının bu bölümünde gösterilen URL ile bir Standard webhook ekleyin. URL şuna benzer: https://your-site/wc-api/adyg_adyen_webhook/. Yöntem olarak JSON 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ı, hangi HMAC anahtarının kullanılacağını belirler. Geçerli imzası olmayan webhook'lar reddedilir ve Adyen bunları daha sonra yeniden dener. Webhook olmadan siparişler Ödeme bekleniyor durumunda kalır.

Eklenti şu olayları işler:

Diğer olaylar sipariş notlarına eklenir. Bu mağazanın bir siparişine ait olmayan bildirimler, örneğin Customer Area'daki test düğmesinin gönderdikleri, kabul edilir ve yok sayılır.

Gelişmiş

Order status after payment: başarılı bir ödemeden sonra, tek bir durum değişikliğiyle ayarlanan sipariş durumu.

Debug log: Log API calls and webhook events seçeneği, WooCommerce > Status > Logs bölümüne, kaynak wcp_adyen_gateway olarak yazar. Hatalar her zaman kaydedilir. Günlükler hiçbir zaman API veya HMAC anahtarlarını ya da alışveriş yapanın kişisel verilerini içermez. Varsayılan: kapalı.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Varsayılan: kapalı.

Ödeme süreci

Müşteri ödeme yöntemini seçer (varsayılan olarak Adyen) ve siparişi verir. Eklenti, sipariş para biriminde sipariş toplamı için bir Adyen ödeme bağlantısı oluşturur ve müşteriyi Adyen ödeme sayfasına yönlendirir. Orada müşteri, Adyen hesabınızda etkin olan herhangi bir yöntemle öder. Müşterinin fatura e-posta adresi, adı ve ülkesi ile mağazanın dili Adyen'e iletilir; ödeme, Order # ve sipariş numarası olarak görünür.

Ödemeden sonra müşteri mağazanızın sipariş alındı sayfasına döner. Dönüşün kendisi siparişi ödenmiş olarak işaretlemez: sipariş, yalnızca Adyen'in imzalı AUTHORISATION webhook'u ile onaylaması ve tutar ile para biriminin siparişle eşleşmesi durumunda ödenmiş olarak işaretlenir.

Ödeme reddedilirse sipariş Başarısız olur ve müşteri yeniden deneyebilir. Müşteri aynı sipariş için yeni bir ödeme başlatırsa, örneğin Pay for order sayfasından, önceki ödeme bağlantısının süresi sona erer ve o bağlantıyla da ödeme yapılamaz.

Ödeme bağlantısı oluşturulamazsa müşteri Payment could not be initiated. Please try again or choose another payment method. mesajını görür. Neden sipariş notlarına eklenir. Ayarlar eksikse müşteri Payment gateway is not configured properly. Please contact the store administrator. mesajını görür.

JPY, KRW, IDR veya VND gibi ondalığı olmayan para birimleri için WooCommerce > Settings > General > Number of decimals değerini 0 olarak ayarlayın. Aksi halde toplam tam birime yuvarlanır.

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

Eklentide abonelik veya yinelenen ödeme, kayıtlı kart, sitede kart alanı (Drop-in veya Components), WooCommerce'te tahsilat veya iptal düğmesi ve webhook'lar için temel kimlik doğrulama (basic authentication) yoktur.

Siparişler ve iadeler

Sipariş durumları

Pending payment: ödeme bağlantısı oluşturuldu ve Adyen ödemeyi henüz onaylamadı. Sipariş notunda ödeme bağlantısı, tutar ve ortam gösterilir.

Processing, Completed or On Hold: ödeme ön provizyon aldı. Durum, Order status after payment ayarını izler. Sipariş notunda tutar, PSP referansı ve ödeme yöntemi gösterilir. İşlem kimliği, Adyen PSP referansıdır.

On hold after payment: Adyen, siparişin toplamından farklı bir tutar veya para birimi onayladı. Sipariş notunda ikisi de gösterilir ve sipariş ödenmiş olarak işaretlenmez. Tahsilat başarısız olursa ödenmiş bir sipariş de beklemeye alınır, çünkü para tahsil edilmemiştir. Ödemeyi Customer Area'da kontrol edin.

Failed: ödeme reddedildi. Ödenmiş, beklemedeki ve iptal edilmiş siparişler reddedilen bir ödeme ile değiştirilmez.

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

Halihazırda ödenmiş bir sipariş için, örneğin eski bir ödeme bağlantısından ikinci bir başarılı ödeme gelirse, sipariş yeniden değiştirilmez. Bir not, olası çift tahsilatı Customer Area'da kontrol etmenizi ve gerekirse orada iade etmenizi ister.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Adyen düğmesine tıklayın. Tam ve kısmi iadeler desteklenir. İade, ödemenin yapıldığı ortama ve satıcı hesabına gönderilir; bu nedenle o ortamın API anahtarı ayarlanmış olmalıdır. Adyen iadeleri eşzamansız işler: talep siparişte not edilir ve nihai sonuç, REFUND veya REFUND_FAILED webhook'u ile sipariş notu olarak eklenir. Adyen talebi kabul etmezse WooCommerce hatayı gösterir ve hiçbir iade kaydedilmez. Adyen'de manuel tahsilat açıksa yalnızca tahsil edilmiş ödemeler iade edilebilir.

Adyen Customer Area'da yapılan iadeler webhook ile gelir ve sipariş notlarına eklenir. Bunlar otomatik olarak WooCommerce iadesi olarak kaydedilmez.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bölümü WooCommerce > Settings > Payments > Adyen sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bölüm durumu gösterir; örneğin lisansın hangi tarihe kadar etkin 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 kullanın. Manage licenses and domains in your account bağlantısı vibefox.net hesabınızı açar.

Bir anahtar bir alan adında çalışır. Anahtarı bir siteden kaldırmak alan adı hakkını serbest bırakmaz; bu hakkı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar yoksa Adyen, ödeme sayfasında müşterilere gösterilmez. Ödeme yine de 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 ödeme yöntemini yine görür; yöntem (unlicensed — visible to admins only) etiketiyle işaretlenir. Böylece bir anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Plugins sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Lisans 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

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 tam olduğunu kontrol edin: Merchant account, o modun API anahtarı ve HMAC anahtarı; canlı modda Live URL prefix. Ayarlar sayfası eksik olanları listeler.

Ödeme yapıldı, ancak sipariş hâlâ Pending payment durumunda: webhook çalışmıyor. Kullandığınız ortamın (test veya canlı) Customer Area'sında Standard webhook'un var olduğunu, URL'sinin ayarlarda gösterilenle tam olarak aynı olduğunu ve yöntemin 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 HMAC anahtarında eklenti HTTP 401 yanıtı verir ve Adyen teslimatı daha sonra yeniden dener; bu nedenle anahtar düzeltildiğinde sipariş otomatik olarak güncellenir. Günlükte Webhook rejected: invalid HMAC signature mesajı veya HMAC anahtarının yapılandırılmadığı bilgisi görünür.

Webhook meşgul yanıtı verir, daha sonra yeniden dener: sipariş, aynı anda başka bir teslimat tarafından işleniyordu. Adyen webhook'u otomatik olarak yeniden dener.

Kaydederken HMAC anahtarı hatası: alan, Customer Area'dan alınan onaltılık HMAC anahtarını içermelidir. Önceki değer korunur.

Müşteri Payment could not be initiated mesajını görüyor: sipariş notlarını açın veya Debug log seçeneğini açıp WooCommerce > Status > Logs bölümünde kaynak wcp_adyen_gateway kayıtlarına bakın. API anahtarını, satıcı hesabını ve canlı modda canlı URL önekini kontrol edin.

Sipariş ödemeden sonra On hold durumunda: sipariş notunu okuyun. Adyen'in onayladığı tutar veya para birimi siparişle eşleşmedi ya da bir tahsilat başarısız oldu. Ayrıca Order status after payment ayarınız da nedeni olabilir.

İade başarısız oluyor: siparişte bir Adyen PSP referansı olmalıdır; bu, AUTHORISATION webhook'u ile gelir. Ödemenin yapıldığı ortamın kimlik bilgileri ayarlanmış olmalıdır. Manuel tahsilatta yalnızca tahsil edilmiş ödemeler iade edilebilir.

Lisans bölümü bir hata gösteriyor: bölümdeki mesajı izleyin. Örneğin anahtar başka bir alan adında zaten kullanılıyorsa, vibefox.net hesabınızda bir alan adı hakkını 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. Tamamen kaldırmak için Plugins sayfasında devre dışı bırakıp silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ağ geçidi ayarları ile siparişlerde saklanan Adyen verileri (PSP referansları, ödeme bağlantıları, işlenmiş olaylar) yalnızca Delete data on uninstall açıksa kaldırılır. Aksi halde yeniden kurulum için saklanır. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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