VibeFox Kushki for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

WooCommerce: 8.0 veya üzeri, kurulu ve etkin. Eklenti WooCommerce olmadan etkinleştirilmez.

PHP: 8.0 veya üzeri.

Mağaza para birimi: USD (Ekvador) veya COP (Kolombiya). Diğer para birimlerinde ödeme yöntemi ödeme sayfasında gizlenir.

HTTPS: Kushki, canlı modda ödeme sayfasının HTTPS üzerinden sunulmasını gerektirir.

Kushki hesabı: Kushki test (UAT) hesabınızın ve canlı hesabınızın Public ve Private Merchant ID'lerine ihtiyacınız var. Bunlar Kushki Console'da Developers > Credentials altındadır. İsteğe bağlı webhook için her hesabın webhook imza anahtarına da ihtiyacınız vardır (bkz. Yapılandırma).

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 bölümüne gidin, eklentinin ZIP dosyasını seçin ve Install Now düğmesine tıklayın. wcp_kushki_payment 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 > Kushki > Manage ya da Plugins sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

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

5. Test Public ve Private Merchant ID'lerini girin ve Test mode seçeneğini açık bırakın. İsteğe bağlı olarak Kushki Console'da webhook'u ayarlayın ve imza anahtarını yapıştırın (bkz. Yapılandırma).

6. Enable / Disable seçeneğini açın ve bir test siparişi verin. Hazır olduğunuzda canlı Merchant ID'lerini (ve canlı webhook imzasını) girin ve Test mode seçeneğinin işaretini kaldırın.

Yapılandırma

Tüm ayarlar tek bir sayfadadır: WooCommerce > Settings > Payments > Kushki. Alanların üstünde sayfa; ödeme yöntemi açık ama geçerli modun Merchant ID'leri eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir), mağaza para birimi desteklenmiyorsa, canlı mod HTTPS olmadan kullanılıyorsa ve geçerli modda webhook imzası yoksa sizi uyarır. Test modu açıkken Test mode is on: the Kushki test environment is used, no real money is charged. mesajını gösterir. Ödeme yöntemi açıkken ve geçerli modun Merchant ID'leri girilmeden kaydederseniz, bunları girmenizi hatırlatan bir hata görünür. Kimliklerin etrafındaki boşluklar kayıt sırasında silinir.

Genel

Enable / Disable: Enable Kushki card payments ö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: Credit / debit card (Kushki).

Description: ödeme sayfasında kart formunun üstünde gösterilen metin. Varsayılan: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

API kimlik bilgileri

Kushki Console'dan (Developers > Credentials) Public ve Private Merchant ID'leri kopyalayın. Test (UAT) ve canlı hesapların kimlikleri farklıdır. Test modu yalnızca test kimliklerini, canlı mod yalnızca canlı kimlikleri kullanır.

Test mode: Use the Kushki test (UAT) environment seçeneği Merchant ID'leri, kart formunu ve API'yi birlikte Kushki test ortamına geçirir. Gerçek para tahsil edilmez ve ödeme sayfasında bir TEST MODE rozeti gösterilir. Varsayılan: açık. Gerçek ödeme almak için işaretini kaldırın.

Test Public Merchant ID: Kushki test hesabınızın Public Merchant ID'si. Kart formunu yükler.

Test Private Merchant ID: Kushki test hesabınızın Private Merchant ID'si. Tahsilat ve iadeler için sunucuda kullanılır.

Live Public Merchant ID: Kushki canlı hesabınızın Public Merchant ID'si.

Live Private Merchant ID: Kushki canlı hesabınızın Private Merchant ID'si. Gizli tutun.

Webhook (önerilir)

Ödemeler Kushki API yanıtıyla hemen onaylanır, bu nedenle webhook zorunlu değildir. Yanıtı kaybolan ödemeleri (örneğin zaman aşımında) ek olarak onaylar ve Kushki Console'da yapılan iptal ve iadeleri bildirir. Kushki Console'da (Webhooks) kart ödemeleri için ayarların bu bölümünde gösterilen URL'yi ekleyin. Şuna benzer: https://your-site/wc-api/webhook_kushki_p/. Bunu hem test hesabı hem de canlı hesap için yapın.

Eklenti bu kart bildirimlerini işler:

Test webhook signature: Kushki test hesabının webhook imza anahtarı (Console > Webhooks).

Live webhook signature: Kushki canlı hesabının webhook imza anahtarı.

Geçerli imzası olmayan webhook'lar reddedilir. İmza anahtarı yoksa tüm webhook bildirimleri reddedilir, ancak ödemeler çalışmaya devam eder, çünkü API yanıtıyla onaylanırlar.

Gelişmiş

Debug log: Log API calls and webhooks Kushki isteklerini ve webhook'larını WooCommerce > Status > Logs sayfasına, kaynak wcp_kushki_payment olarak yazar. Hatalar her zaman kaydedilir. Günlükler hiçbir zaman Merchant ID, kart jetonu veya müşteri e-postası içermez. Varsayılan: kapalı.

Delete data on uninstall: açıksa eklentiyi silmek ayarları ve günlükleri kaldırır. Siparişler ve Kushki referansları korunur. Varsayılan: kapalı.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Credit / debit card (Kushki)). Altında, sipariş para biriminde sipariş toplamıyla birlikte Kushki kart formu görünür. Pay for order sayfasında form sipariş toplamını kullanır. Müşteri kartını girer, Kushki formu taksit sunuyorsa taksit seçer ve Kushki formunun içindeki ödeme düğmesine basar.

Klasik ödeme sayfasında Kushki seçiliyken WooCommerce'in Place order düğmesi gizlenir: kart kabul edildikten sonra sipariş otomatik olarak gönderilir. Ödeme bloğunda müşteri yine Kushki formunun içindeki ödeme düğmesine basar. Müşteri bunu yapmadan siparişi vermeye çalışırsa Please enter your card details in the Kushki form and press its pay button. mesajı gösterilir.

Mağazanız kartı ardından sunucuda tahsil eder. Sipariş, Kushki onu bir fiş numarasıyla onaylayana kadar ödenmiş olarak işaretlenmez ve müşteri doğrudan sipariş alındı sayfasına gider. Kushki onaylanan bir tutar veya para birimi bildirirse, bunlar siparişle karşılaştırılır.

Kart reddedilirse müşteri Kushki'den gelen nedenle birlikte Your payment was declined mesajını görür ve aynı formda başka bir kart deneyebilir. Ağ, anahtar veya sunucu sorunlarında müşteri The payment could not be processed right now. Please try again in a moment or choose another payment method. mesajını görür. Teknik neden sipariş notlarına ve günlüğe eklenir. Bir ödeme işlenirken ikinci kez tıklanırsa A payment for this order is already being processed. Please wait a moment and check your order status. mesajı gösterilir.

Ö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. 3-D Secure, dolandırıcılık kuralları ve sunulan taksitler Kushki Console'da ayarlanır.

Eklenti yalnızca tek adımlı kart ödemelerini kabul eder. Kısmi iade, kayıtlı kart, abonelik veya Add payment method yoktur; nakit, banka havalesi (PSE) veya yönlendirmeli banka kartı ödemesi yoktur; ayrı yetkilendirme ve tahsilat da yoktur.

Siparişler ve iadeler

Sipariş durumları

Pending payment: sipariş oluşturuldu ve kart henüz tahsil edilmedi.

Processing: Kushki tahsilatı onayladı (API yanıtıyla veya webhook ile). Yalnızca sanal indirilebilir ürün içeren siparişler WooCommerce varsayılanı olarak Completed olur. Sipariş notu modu, Kushki fiş numarasını ve referansı gösterir. İşlem kimliği Kushki işlem referansıdır (veya fiş numarası).

On hold: Kushki, fiş numarası olmadan bir başarı döndürdü veya siparişten farklı bir tutar ya da para birimi bildirdi. Sipariş notu bunu açıklar. İşlemi Kushki Console'da kontrol edin, ardından siparişi tamamlayın veya ödemeyi iade edin.

Failed: kart reddedildi veya tahsilat yapılamadı. Sipariş notu Kushki kodunu ve mesajını gösterir. Müşteri yeniden ödeme yapabilir.

Bir webhook, zaten ödenmiş, iptal edilmiş veya iade edilmiş bir sipariş için başka bir onaylanan tahsilat bildirirse sipariş değiştirilmez. Bir not, çifte tahsilat olup olmadığını kontrol etmenizi ve Kushki Console'da iade etmenizi ister. Canlı bir sipariş için test ortamından gelen webhook (ya da tersi) bir notla yok sayılır.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tüm sipariş toplamını girin ve Refund via Credit / debit card (Kushki) düğmesine tıklayın (düğmede Title değeriniz görünür). Kushki tüm ödemeyi iade eder, bu nedenle yalnızca tam iadeler kabul edilir. Kısmi tutar için eklenti Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. mesajını gösterir. Bir ödeme yalnızca bir kez iade edilebilir.

İade, ödemenin yapıldığı modda (test veya canlı) gönderilir, bu nedenle o modun Private Merchant ID'si girilmiş olmalıdır. Kushki iadeyi kabul etmezse WooCommerce hatayı gösterir ve hiçbir iade kaydedilmez. Başarılı bir iade, Kushki iade fişiyle birlikte sipariş notlarına eklenir.

Kushki Console'da yapılan iptaller ve 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 bloğu WooCommerce > Settings > Payments > Kushki sayfasının üstündedir. 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 etkin olduğu ve alan adınız. Check now ile durumu yeniden kontrol edin, Change key ile başka bir anahtar girin ve Remove key ile anahtarı bu siteden kaldırı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 o sitenin alan adı hakkını serbest bırakmaz. Hakkı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan Kushki, ö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 ödeme yöntemini (unlicensed — visible to admins only) işaretiyle görmeye devam eder, böylece anahtar satın almadan önce eklentiyi kurup test edebilirsiniz. Eklentiler sayfasında ve WooCommerce sayfalarında bir hatırlatma görünür. Mevcut siparişler etkilenmez: webhook'lar işlenmeye devam eder 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

Ödeme sayfasında Kushki görünmüyor: lisansın etkin olduğunu, Enable / Disable seçeneğinin açık olduğunu ve geçerli modun iki Merchant ID'sinin de olduğunu kontrol edin: test modunda test kimlikleri, canlı modda canlı kimlikler. Mağaza para biriminin (veya Pay for order sayfasındaki sipariş para biriminin) USD veya COP olduğunu kontrol edin. Ayarlar sayfası bu sorunların her biri için bir uyarı gösterir.

Ödeme gerçekleşti ama sipariş Failed veya Pending payment durumunda kaldı: Kushki API yanıtı kaybolmuştur, örneğin zaman aşımı nedeniyle. Webhook bu ödemeleri onaylar. Kushki Console'da webhook URL'sinin ayarlarda gösterilenle birebir aynı olduğunu, kullandığınız modun hesabı için geçerli olduğunu ve o hesabın imza anahtarının ilgili alanda (Test webhook signature veya Live webhook signature) olduğunu kontrol edin. Ödenen tutar ve para birimi olmadan onaylanan bir tahsilat bunun yerine siparişi beklemeye alır.

Webhook, Webhook signature not configured yanıtını veriyor: hiçbir webhook imzası ayarlanmamış. İmza anahtarını ayarlara yapıştırın.

Webhook, Invalid signature yanıtını veriyor: imza anahtarı başka bir hesaba veya moda ait ya da bildirim yolda değiştirilmiş.

Webhook, Order mismatch yanıtını veriyor: bildirim bu siparişe ait değil (yanlış sipariş anahtarı veya işlem). Sipariş değiştirilmez.

Webhook, Busy, retry later yanıtını veriyor: sipariş aynı anda başka bir istek tarafından işleniyordu. Kushki bildirimi yeniden gönderebilir.

Kart formu yüklenmiyor: müşteri The Kushki card form could not be loaded. Please reload the page or choose another payment method. mesajını görür. Geçerli modun Public Merchant ID'sini kontrol edin.

Müşteri This payment option is not available in this store. Please pay by card. mesajını görüyor: Kushki formunda kart olmayan bir ödeme seçeneği seçildi. Eklenti yalnızca kartları tahsil eder.

Müşteri ödeme sırasında bir hata görüyor: sipariş notlarını açın veya Debug log seçeneğini etkinleştirip WooCommerce > Status > Logs sayfasında wcp_kushki_payment kaynağına bakın. Yanlış veya eksik bir Private Merchant ID, ödemenin işlenemediğine dair genel mesajı verir.

İade mod ile ilgili bir mesajla başarısız oluyor: ödeme test veya canlı modda yapıldı ve o modun Private Merchant ID'si girilmemiş. Girin ve yeniden deneyin.

İade No Kushki ticket number found for this order mesajıyla başarısız oluyor: siparişin onaylanmış bir Kushki tahsilatı yok. Kushki Console'da iade edin.

Diğer para birimleri: geliştiriciler, kushki_p_supported_currencies filtresiyle para birimi listesini kendi sorumluluklarında değiştirebilir. Para birimi Kushki hesabınızda etkin olmalıdır.

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 hakkı 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 Plugins sayfasında devre dışı bırakın ve silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman kaldırılır. Ödeme ağ geçidi ayarları ve günlükler yalnızca Delete data on uninstall açıksa kaldırılır. Aksi halde, sonraki yeniden kurulum için kalırlar. Mevcut siparişler ödeme notlarını, Kushki fiş numaralarını ve işlem kimliklerini korur.

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