Ödeme yöntemi ayarlarda var, kasada yok

Belirti

WooCommerce → Ayarlar → Ödemeler ekranında yöntem etkin görünür. Ayarlar kaydedilmiştir, hata kaydında bir şey yoktur. Ama ödeme sayfasında yalnızca havale ya da kapıda ödeme listelenir; özel geçidiniz yoktur.

Bu durumla Castor Coffee'nin QNB sanal POS entegrasyonunu incelerken karşılaştık: aynı çok siteli kurulumdaki perakende mağaza kısa kodlu klasik ödeme sayfasını kullanıyordu, kurumsal mağaza ise blok tabanlı olanı. Eklenti kodu doğruydu, hash hesapları bankanın beklediğiyle birebir aynıydı — ama kurumsal sitede yöntem, ayarlar tamamlansa bile hiçbir zaman görünmeyecekti.

Hangi ödeme sayfası?

İlk soru eklentiyle değil, sayfayla ilgilidir. Ödeme sayfasının içeriğine bakın:

wp post get $(wp option get woocommerce_checkout_page_id) --field=post_content | head -c 200

• <!-- wp:woocommerce/checkout --> ile başlıyorsa blok ödeme sayfası
• [woocommerce_checkout] görüyorsanız klasik ödeme sayfası

Çok siteli kurulumlarda bunu her site için ayrı kontrol edin; siteler farklı zamanlarda kurulduysa farklı türde ödeme sayfaları olabilir.

Neden görünmüyor

Klasik ödeme sayfası PHP ile sunucuda çizilir; WooCommerce etkin geçitleri dolaşır, her birinin payment_fields() çıktısını sayfaya basar. Blok ödeme sayfası ise tarayıcıda çalışan bir React uygulamasıdır ve sepet/ödeme verisini Store API'den alır. Hangi yöntemin nasıl görüneceğini bilmesi için JavaScript tarafında kayıtlı bir tanım gerekir.

WooCommerce bu tanımı klasik geçitten türetmez. Sonuç: geçidiniz sunucuda kayıtlıdır, is_available() doğru döner, ama blok ödeme sayfasının haberi yoktur.

PHP kaydı

Önce blok tarafına geçidi tanıtan bir sınıf yazılır. $name değeri geçidin id'siyle birebir aynı olmalıdır:

use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;

final class My_Gateway_Blocks extends AbstractPaymentMethodType {
    protected $name = 'my_gateway';   // WC_Payment_Gateway::$id ile aynı

    public function initialize() {
        $this->settings = get_option( 'woocommerce_my_gateway_settings', array() );
    }

    public function is_active() {
        $gateways = WC()->payment_gateways()->payment_gateways();
        return isset( $gateways[ $this->name ] ) && $gateways[ $this->name ]->is_available();
    }

    public function get_payment_method_script_handles() {
        wp_register_script( 'my-gateway-blocks', plugins_url( 'assets/blocks.js', __FILE__ ),
            array( 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-html-entities' ), '1.0', true );
        return array( 'my-gateway-blocks' );
    }

    public function get_payment_method_data() {
        return array( 'title' => 'Kredi / Banka Kartı', 'supports' => array( 'products' ) );
    }
}

add_action( 'woocommerce_blocks_payment_method_type_registration', function ( $registry ) {
    $registry->register( new My_Gateway_Blocks() );
} );

is_active() içinde geçidin kendi is_available() kararını kullanmak önemlidir: kimlik bilgileri eksikken ya da para birimi uymazken yöntem blok ödeme sayfasında da gizli kalır, iki sayfa türü aynı kuralla davranır.

Ayrıca ana eklenti dosyasında blok uyumluluğunu bildirin; aksi hâlde editör eklentiyi uyumsuz olarak işaretleyebilir:

add_action( 'before_woocommerce_init', function () {
    \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
} );

JavaScript kaydı

get_payment_method_data() ile gönderilen veri, tarayıcıda <name>_data anahtarıyla okunur. Derleme adımı gerektirmeyen en küçük kayıt:

( function () {
    var settings = window.wc.wcSettings.getSetting( 'my_gateway_data', {} );
    var el = window.wp.element.createElement;
    var label = settings.title || 'Kredi / Banka Kartı';

    window.wc.wcBlocksRegistry.registerPaymentMethod( {
        name: 'my_gateway',                 // PHP'deki $name ile aynı
        label: el( 'span', null, label ),
        ariaLabel: label,
        content: el( 'p', null, 'Güvenli ödeme sayfasına yönlendirileceksiniz.' ),
        edit: el( 'p', null, 'Güvenli ödeme sayfasına yönlendirileceksiniz.' ),
        canMakePayment: function () { return true; },
        supports: { features: settings.supports || [ 'products' ] }
    } );
} )();

Müşteriyi bankanın 3D sayfasına yönlendiren geçitlerde başka bir şey gerekmez: geçidin process_payment() metodu redirect adresi döndürdüğünde blok ödeme sayfası müşteriyi o adrese götürür. Kart bilgisini kendi sayfanızda alan geçitlerde ise ek olarak onPaymentSetup olayıyla ödeme verisini Store API'ye taşımanız gerekir.

Sessiz tuzaklar

Kayıt yapıldığı hâlde yöntem görünmüyorsa, sırasıyla şunlara bakın. Hiçbiri ekranda hata üretmez:

• İsim uyuşmazlığı: geçidin id'si, PHP'deki $name ve JavaScript'teki name üçü birden aynı olmalı
• Ertelenen betik: hız eklentisi betiği erteliyorsa kayıt, wc.wcBlocksRegistry hazır olmadan çalışır ya da hiç çalışmaz — ödeme sayfasını optimizasyondan muaf tutun
• Eksik bağımlılık: wc-blocks-registry bağımlılık listesinde yoksa konsolda wc is not defined görülür
• is_active() yanlış dönüyor: eksik ayar, desteklenmeyen para birimi ya da yanlış kurgulanmış koşul
• Önbellek: sayfa önbelleği eski betik listesini sunuyor olabilir; değişiklikten sonra ödeme sayfasının önbelleğini temizleyin

Doğrulama

Sunucu tarafında kaydın gerçekleştiğini WP-CLI ile görebilirsiniz:

wp eval '
$r = Automattic\WooCommerce\Blocks\Package::container()
      ->get( Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry::class );
do_action( "woocommerce_blocks_payment_method_type_registration", $r );
echo implode( ", ", array_keys( $r->get_all_registered() ) );'

Listede yönteminizin adı yoksa sorun PHP kaydındadır. Varsa ama ödeme sayfasında görünmüyorsa tarayıcıda betiğin yüklenip yüklenmediğine ve konsol hatalarına bakın; son olarak is_active() kararını kontrol edin.

Özet

Blok ödeme sayfası, klasik ödeme geçitleri için ayrı bir kapıdır ve o kapıdan ancak kayıtla geçilir. Teşhis tek komutla başlar: ödeme sayfası blok mu, kısa kod mu? Blok ise geçit için bir AbstractPaymentMethodType sınıfı ve bir registerPaymentMethod çağrısı yazın, üç yerdeki ismi aynı tutun ve betiği ertelemeyin. Ödeme almaya hazır görünen ama müşteriye hiç görünmeyen bir yöntem, en pahalı hatalardan biridir — çünkü kimse şikâyet etmez, satış sadece olmaz.