Pluxee Pay for WooCommerce

Pluxee (eski adıyla Sodexo) Türkiye mobil ödeme kodu (OTP) ile WooCommerce mağazanızda ödeme almanızı sağlayan ödeme ağ geçidi eklentisi.

---

Türkçe

Ne işe yarar

Müşterileriniz sepeti onaylarken ödeme yöntemi olarak "Pluxee ile Öde"yi seçer, Pluxee mobil uygulamasına kayıtlı GSM numarasını ve uygulamadan aldığı 6 haneli tek kullanımlık kodu (OTP) girer. Eklenti bu kodu Pluxee'nin SOAP web servisine (LoginWsUser → CreateActionToken → MakePayment) iletip sonucu WooCommerce siparişine işler.

Öne çıkan özellikler:

• Klasik checkout ve WooCommerce Blocks checkout desteği
• HPOS (yüksek performanslı sipariş tabloları) ve cart_checkout_blocks uyumluluk bildirimleri
• UAT ve canlı (PROD) ortam bilgileri birbirinden bağımsız saklanır
• VKN girilerek sanal POS (üye no / terminal no) bilgilerinin otomatik çekilmesi
• Yanıt alınamayan (zaman aşımına uğrayan) ödemelerde otomatik teknik iptal (TxnStatus=R) — çift çekim koruması
• Gıda dışı ürünler için ayarlanabilir uygunluk kuralı (Pluxee sözleşmesi gıda dışı üründe Pluxee Online Ödeme'yi yasaklar) ve [pluxee_notice] kısa kodu ile zorunlu bilgilendirme metni
• WooCommerce iade aracından Pluxee MakeRefund ile kısmi/tam iade
• İşlem kayıt tablosu, mutabakat ekranı ve CSV dışa aktarma
• wp pluxee test-connection / wp pluxee info WP-CLI komutları
• GitHub Releases üzerinden otomatik güncelleme kontrolü

Gereksinimler

• WordPress 6.4+
• WooCommerce 8.0+
• PHP 7.4+ (openssl ve mbstring uzantıları)
• Bir Pluxee üye işyeri sözleşmesi ve Pluxee'den alınmış servis kullanıcı bilgileri (WS kullanıcı adı/şifresi, üye no, terminal no, HMAC anahtarı, RSA açık anahtarı)

Kurulum

1. GitHub Releases sayfasından en güncel pluxee-for-woocommerce.zip dosyasını indirin (kaynak kod sekmesindeki otomatik ZIP değil, Release varlıkları arasındaki dosya — vendor/ dahil kurulabilir hâlde paketlenmiştir).
2. WordPress yönetim panelinde Eklentiler > Yeni Ekle > Eklenti Yükle üzerinden ZIP'i yükleyin, ya da dosyayı doğrudan /wp-content/plugins/pluxee-for-woocommerce dizinine açın.
3. Eklentiyi etkinleştirin.

Yapılandırma adımları

WooCommerce > Ayarlar > Ödemeler > Pluxee ile Öde ekranından, sırasıyla:

1. Ortam — UAT (test) veya PROD (canlı) seçin. Her ortamın kullanıcı adı, şifre, üye no, terminal no, HMAC anahtarı ve açık anahtarı ayrı saklanır; ortam değiştirmek diğerinin bilgilerini silmez.
2. WS bilgilerini girin — Pluxee'den aldığınız servis kullanıcı adı ve şifresini, üye/terminal numaralarını girin.
3. VKN ile sanal POS bilgilerini çekin (isteğe bağlı) — VKN alanını doldurup "VKN ile sanal POS bilgilerini çek" düğmesine basarsanız üye no ve terminal no alanları Pluxee'den otomatik doldurulur. Sonucu kaydetmeyi unutmayın.
4. Değişiklikleri kaydedin.
5. Bağlantıyı test edin — "Bağlantıyı test et" düğmesi LoginWsUser çağrısını dener ve RSA açık anahtarının okunabilir olup olmadığını bildirir.
6. RSA açık anahtarını yapıştırın — Pluxee'nin verdiği PaymentPublicKey dosyasının içeriğini (.NET XML veya PEM biçiminde) açık anahtar alanına yapıştırın.

⚠️ Kaydetmeden test etmeyin. "Bağlantıyı test et" aracı RSA açık anahtarını formdaki değerden değil, veritabanına kaydedilmiş ayardan okur. Yeni bir açık anahtar yapıştırdıktan sonra önce sayfanın altındaki "Değişiklikleri kaydet" düğmesine basıp ayarları kaydedin, testi ancak ondan sonra çalıştırın — aksi hâlde eski (veya boş) anahtar sınanır ve yanıltıcı bir sonuç alırsınız.

⚠️ IP kısıtı. Pluxee, tüm servislerinde çağıran sunucunun IP adresini kısıtlar. Ayar ekranındaki "Araçlar" kutusunda gösterilen sunucunuzun çıkış IP adresini Pluxee'ye (üye işyeri temsilcinize veya PartnerOperasyon.Tr@pluxeegroup.com adresine) bildirip yetkilendirilmesini istemeden hiçbir servis çağrısı (bağlantı testi dahil) başarılı olmaz.

Gıda dışı ürün kuralı ve [pluxee_notice]

Pluxee sözleşmesi gereği giyim, elektronik, kozmetik, kırtasiye gibi gıda dışı ürünlerde Pluxee Online Ödeme sunulamaz. Ürün Uygunluğu bölümünden kural modu seçilir:

• Kapalı — tüm ürünlerde ödeme yöntemi gösterilir.
• Yalnızca seçili kategorilerde göster — beyaz liste.
• Seçili kategorilerde gizle — kara liste.

Alt kategoriler otomatik kapsama dahildir. Sepette uygun olmayan ürün varsa Pluxee ödeme yöntemi ödeme sayfasında gizlenir ve sepete özel bir uyarı gösterilir. Pluxee ayrıca anasayfada zorunlu bir bilgilendirme metni ister; bu metni [pluxee_notice] kısa kodu ile istediğiniz sayfaya (genellikle anasayfaya) yerleştirin.

Sorun giderme

Hata / durum	Anlamı
"WS kullanıcı adı ve şifresi gereklidir"	Ayar ekranında kullanıcı adı/şifre alanları boş; önce doldurup kaydedin.
"Bağlantı başarısız: … Pluxee IP kısıtı uygular; sunucunuzun çıkış IP adresi (…) Pluxee tarafında yetkilendirilmiş olmalıdır."	Sunucu IP'si Pluxee tarafında tanımlı değil. Gösterilen IP'yi Pluxee'ye bildirin.
"RSA açık anahtarı henüz girilmemiş" / "RSA açık anahtarı okunamadı"	Açık anahtar alanı boş ya da beklenen .NET XML/PEM biçiminde değil; ve/veya kaydetmeden test ettiniz (yukarıdaki uyarıya bakın).
"Lütfen önce VKN alanını doldurun"	Sanal POS çekme aracı VKN olmadan çalışmaz.
Ödeme reddedildi, sipariş "Beklemede" kaldı	Pluxee ResultCode sıfırdan farklı döndü; sipariş notunda ve işlem kayıt tablosunda ayrıntı vardır. Mesaj metni pluxee_wc_error_message süzgeciyle özelleştirilebilir.
Ödeme "yanıt alınamadı" ile başarısız oldu ama Pluxee tarafında işlem geçmiş olabilir	Eklenti otomatik olarak teknik iptal (TxnStatus=R) dener; bu durum işlem kayıt tablosunda technical_reversal olarak görünür.

Hata ayıklama için Gelişmiş bölümündeki "Hata ayıklama kayıtları"nı açın; ham istek/yanıtlar (hassas alanlar maskelenmiş olarak) WooCommerce > Durum > Kayıtlar altında görünür.

İade süreci

Bu sürümde otomatik iade (MakeRefund) yoktur. İadeler Pluxee üye işyeri panelinden elle yapılır; sipariş detay sayfasındaki Pluxee kutusunda gösterilen RRN (işlem referans numarası) değerini kullanın. Otomatik iade desteği yol haritasında (bkz. CHANGELOG.md).

Geliştirme

cd wp-content/plugins/pluxee-for-woocommerce
composer install
vendor/bin/phpunit

Testler WordPress'e bağımlı değildir (saf PHPUnit birim testleri, WP fonksiyonları test çiftleriyle sahnelenir). CI, PHP 7.4/8.1/8.3 matrisinde php -l + composer install + vendor/bin/phpunit çalıştırır (bkz. .github/workflows/ci.yml).

Bilinen uyarılar (wp plugin check)

wp plugin check pluxee-for-woocommerce çalıştırıldığında aşağıdaki bulgular bilinçli olarak düzeltilmemiştir; her biri geliştirme dizinini (.git dahil, dağıtım paketi değil) taradığı için ya WordPress.org'a özgü kurallardan ya da bu eklentinin dağıtım modelinden kaynaklanır:

• GitHub tabanlı otomatik güncelleyici (includes/Update/class-github-updater.php, plugin_updater_detected ERROR + update_modification_detected x2 WARNING). Bu eklenti WordPress.org'da barındırılmıyor; GitHub Releases üzerinden dağıtılıyor (bkz. PLUXEE_WC_GITHUB_REPO), bu yüzden kendi güncelleme denetleyicisine ihtiyacı var. WP.org kısıtlaması burada geçerli değil.
• readme.txt Türkçe (readme_short_description_non_official_language, readme_description_non_official_language ERROR). Eklenti yalnızca Türkiye pazarı ve Pluxee/Sodexo Türkiye entegrasyonu için yazıldı, WordPress.org'a gönderilmeyecek; İngilizce zorunluluğu WP.org readme diline özgü bir kural.
• load_plugin_textdomain() (pluxee-for-woocommerce.php, discouraged function WARNING). 4.6 sonrası WP.org bu çağrıyı kendisi hallediyor, ama bu eklenti WP.org'da olmadığından languages/ dizinindeki çevirilerin yüklenmesi için çağrı hâlâ gerekli.
• phpunit.xml.dist (application_detected ERROR). Plugin Check'in "uygulama dosyası" denetimi, dosya adını uzantı listesiyle (a, bin, … dist, …) eşleştiriyor ve phpunit.xml.dist .dist ile bittiği için yanlış pozitif üretiyor — dosya bir ikili/derlenmiş uygulama değil, PHPUnit'in standart "yerel phpunit.xml'e kopyalanacak şablon" adlandırma kuralı (vendor/plugin-check/includes/Checker/Checks/Plugin_Repo/File_Type_Check.php, look_for_application_files()). Dosya .distignore'da listeli, dağıtım paketine girmiyor.
• Geliştirme/test dosyaları — .gitignore, .distignore, .phpunit.result.cache, .superpowers/, .github/, tests/** (hidden_files, github_directory, NonPrefixedFunctionFound bulguları). wp plugin check bu dev klasörünü olduğu gibi tarıyor; gerçek dağıtım paketi rsync --exclude-from=.distignore ile üretiliyor ve bu dosyaların hiçbiri pakete girmiyor (bkz. .distignore). tests/bootstrap.php WordPress yokken saf PHPUnit ile çalışacak şekilde tasarlandı; testler autoloader yüklenmeden önce sahte bir ABSPATH sabiti tanımlayarak eklenti dosyalarındaki defined( 'ABSPATH' ) || exit; korumasıyla uyumlu çalışır (bkz. tests/bootstrap.php), bu yüzden __()/esc_html() gibi yedek çeviri fonksiyonları hâlâ NonPrefixedFunctionFound uyarısı üretir ama artık missing_direct_file_access_protection ya da ExceptionNotEscaped üretmez — bu iki bulgu gerçek kod düzeltmeleriyle giderildi (tüm includes/**/*.php dosyalarına ABSPATH koruması eklendi; tests/Doubles/FakeTransport.php'teki istisna mesajı esc_url()'den geçiriliyor).

Kod içindeki gerçek/düzeltilebilir bulgular (escaping, çeviri yorumları, prepare() kapsamı, $_POST['password']'ün bilinçli olarak sanitize_text_field()'tan geçirilmemesi, php://output akışına WP_Filesystem yerine fopen()/fwrite()/fclose() kullanımı vb.) giderildi veya ilgili satırın hemen üzerinde gerekçeli phpcs:ignore/phpcs:disable yorumuyla işaretlendi.

Süzgeç listesi

Kod tabanında tanımlı süzgeçlerin tam listesi ve açıklamaları aşağıdaki tabloda. Bu sürümde eklentiye özgü bir do_action() kancası yoktur — yalnızca aşağıdaki apply_filters() süzgeçleri kullanılabilir.

Süzgeç	Parametreler	Varsayılan	Ne işe yarar
pluxee_wc_enable_updater	bool $enabled	true	GitHub Releases üzerinden otomatik güncelleme denetimini açar/kapatır.
pluxee_wc_external_info	string $external_info	Ayar değeri, yoksa site adı	MakePayment isteğindeki ExternalInfo alanını değiştirir.
pluxee_wc_payment_field_order	string[] $order	SoapRequest::PAYMENT_FIELD_ORDER	MakePayment XML gövdesindeki alan sırasını değiştirir.
pluxee_wc_ws_token_ttl	int $ttl	Client::TOKEN_TTL	WsToken önbellek ömrünü (saniye) değiştirir; sonuç en az 60 saniyeye sabitlenir.
pluxee_wc_request_timeout	int $timeout	Credentials::timeout()	SOAP isteği zaman aşımını (saniye) değiştirir; sonuç en az 5 saniyeye sabitlenir.
pluxee_wc_product_eligible	bool $eligible, int $product_id	Uygunluk motorunun (bkz. §6) hesapladığı sonuç	Bir ürünün Pluxee ile ödenebilirliğini değiştirir. Ürün bazlı _pluxee_eligible override (yes/no) bu süzgeçten önce döner ve süzgece uğramaz.
pluxee_wc_error_message	string $message, int\|null $code	Pluxee yanıtındaki hata mesajı veya genel bir metin	Reddedilen ödemede müşteriye gösterilecek mesajı değiştirir.

---

English

What it does

Lets your customers pay at WooCommerce checkout with a Pluxee (formerly Sodexo) Turkey mobile payment code: they enter the phone number registered in the Pluxee app and the one-time code (OTP) it generates, and the plugin settles the payment through Pluxee's SOAP web service (LoginWsUser → CreateActionToken → MakePayment).

Highlights: classic and WooCommerce Blocks checkout support, HPOS compatibility, separate UAT/PROD credential storage, one-click virtual POS lookup by tax ID (VKN), automatic technical reversal for timed-out payments, a configurable non-food product eligibility rule, a transaction log with reconciliation screen and CSV export, WP-CLI diagnostics (wp pluxee test-connection, wp pluxee info), and self-updates from GitHub Releases.

Requirements

WordPress 6.4+, WooCommerce 8.0+, PHP 7.4+ with the openssl and mbstring extensions, and an active Pluxee merchant contract with issued web-service credentials and an RSA public key.

Installation

Download the packaged ZIP from GitHub Releases (the release asset, not the source-code archive) and install it through Plugins > Add New > Upload Plugin, or unzip it into /wp-content/plugins/pluxee-for-woocommerce. Activate the plugin.

Configuration

Under WooCommerce > Settings > Payments > Pluxee Pay: pick the environment (UAT/PROD), enter the web-service credentials, optionally fetch merchant/terminal numbers by tax ID, save the settings, then run "Test connection". Paste the RSA public key Pluxee provided.

⚠️ Save before testing. The "Test connection" tool reads the RSA public key from the saved setting, not from the form. Save settings right after pasting a new public key, before clicking "Test connection" — otherwise the tool tests the old (or empty) key.

⚠️ IP allow-listing. Pluxee enforces an IP restriction on every service call. Report the outbound server IP shown in the settings screen to Pluxee and have it allow-listed before any call — including the connection test — will succeed.

Non-food rule and refunds

The Pluxee contract forbids offering Pluxee Online Payment for non-food products; configure the eligibility rule (off / allow-list / deny-list) and category list under Product Eligibility, and place the mandatory disclosure text with the [pluxee_notice] shortcode. There is no automated refund flow in this version — refunds are processed manually in the Pluxee merchant portal using the RRN shown on the order.

Development

cd wp-content/plugins/pluxee-for-woocommerce
composer install
vendor/bin/phpunit

---

Süzgeçler / Filters

Süzgeç	Konum	Açıklama
pluxee_wc_request_timeout	Api\Client::call()	Pluxee SOAP isteklerinin zaman aşımı süresini (saniye) değiştirir. Varsayılan, ayar ekranındaki "İstek zaman aşımı" değeridir.
pluxee_wc_ws_token_ttl	Api\Client::ws_token()	LoginWsUser ile alınan WsToken'ın önbellekte kaç saniye tutulacağını belirler (varsayılan Client::TOKEN_TTL = 600 sn, en az 60 sn'ye zorlanır).
pluxee_wc_payment_field_order	Api\SoapRequest::create_action_token() (ve ilgili istek oluşturucular)	MakePayment/CreateActionToken SOAP zarfındaki alanların gönderim sırasını değiştirir.
pluxee_wc_error_message	Gateway\PaymentProcessor::customer_message()	Reddedilen ödemede müşteriye gösterilecek mesajı, Pluxee ResultCode değeriyle birlikte özelleştirmeye izin verir.
pluxee_wc_enable_updater	Plugin::init() (GitHub güncelleyici kaydı)	false döndürülürse GitHub Releases'ten otomatik güncelleme kontrolü devre dışı kalır.

Not: Bu tablo yalnızca kod tabanında apply_filters() ile fiilen tanımlı süzgeçleri listeler (grep -rn "apply_filters" includes/ ile doğrulanmıştır). Daha önce planlanan pluxee_wc_product_eligible süzgeci bu sürümde uygulanmadı; ürün uygunluğu tamamen ayar ekranındaki "Ürün Uygunluğu" kural/kategori seçenekleriyle yönetilir, kodla geçersiz kılınamaz.

Güvenlik

• Açık OTP hiçbir zaman saklanmaz. Müşterinin girdiği 6 haneli kod yalnızca bellekte Security\OtpEncryptor ile RSA/OAEP şifrelenip Pluxee'ye TxnCode olarak gönderilir; ne veritabanına ne loglara açık hâliyle yazılır.
• GSM numaraları loglarda maskelenir (Support\Redactor::mask_gsm()): yalnızca ilk iki ve son bir hane görünür kalır, geri kalanı * ile değiştirilir.
• Sır değerleri (şifreler, WsToken, ActionToken, şifrelenmiş TxnCode, kart numaraları) hata ayıklama günlüklerinde Support\Redactor tarafından maskelenir — hem SOAP XML gövdesinde hem de log bağlamı dizilerinde, gerekirse iç içe geçmiş dizilerde de.
• Kimlik bilgileri (kullanıcı adı, şifre, üye/terminal no, HMAC anahtarı, RSA açık anahtarı) WooCommerce ödeme yöntemi ayarı olarak standart WordPress wp_options tablosunda saklanır; bu, diğer tüm WooCommerce ödeme ağ geçitleriyle aynı depolama modelidir. Daha katı bir dağıtım isteyen kurulumlar, her alanı wp-config.php içindeki PLUXEE_WC_WS_USERNAME, PLUXEE_WC_WS_PASSWORD, PLUXEE_WC_MERCHANT_NO, PLUXEE_WC_TERMINAL_NO, PLUXEE_WC_HMAC_KEY, PLUXEE_WC_PUBLIC_KEY sabitleriyle geçersiz kılıp veritabanından tamamen çıkarabilir (bu alanlar o zaman ayar ekranında salt okunur görünür).
• Kaldırma sırasında hiçbir şey silinmez, meğer ki "Kaldırma" ayarındaki "Eklenti silinirken tüm ayarları ve işlem kayıtlarını sil" kutusu işaretlenmiş olsun (delete_data_on_uninstall = yes). İşaretliyse uninstall.php işlem tablosunu, eklenti ayarlarını ve önbelleğe alınmış token/IP değerlerini temizler.

Lisans

GPL-2.0-or-later. Bkz. LICENSE.