WooCommerce Sanal POS Entegrasyonu: 3D Secure, İade ve Mutabakat

WooCommerce sanal POS’ta “ödeme alındı, sipariş beklemede” sorununun nedenleri: 3D Secure akışı, callback doğrulama, durum eşleştirme, iade ve gün sonu mutabakatı.
Teknik özet
Teknoloji
WooCommerce, EMV 3-D Secure, PCI DSS, HMAC, WP-CLI
Konu
Sanal POS ve ödeme kuruluşu entegrasyonunda ödeme, iade ve mutabakat akışı
Seviye
Orta–ileri
Ön koşullar
  • WooCommerce sipariş durumlarına aşinalık
  • PHP ve WordPress eylem/filtre yapısı bilgisi
  • Ödeme sağlayıcısının test ortamı erişimi
Bu yazıda7 bölüm

“Kart çekildi ama sipariş hâlâ Ödeme bekleniyor” şikâyeti, WooCommerce sanal POS entegrasyonlarında en sık açılan destek kaydıdır. Eklentiyi etkinleştirip mağaza anahtarını girmek işin kolay kısmı. Zor kısım şunlar: 3D Secure dönüşünü doğrulamak, siparişi doğru duruma almak, iade ve iptalleri banka kaydıyla aynı tutmak, gün sonunda tahsilatı muhasebeyle eşleştirmek. Aşağıdaki sıra, e-ticaret yöneticisinin ve WooCommerce geliştiricisinin canlıya almadan önce elden geçirmesi gereken noktaları kapsıyor.

Doğrudan banka POS’u mu ödeme kuruluşu mu

Kurumsal e-ticaret projelerinde ilk karar, tahsilatı doğrudan bir bankanın sanal POS’undan mı, yoksa 6493 sayılı Kanun kapsamında lisanslı bir ödeme kuruluşundan mı alacağınızdır. Teknik akış benzer görünür. Sözleşme, entegrasyon yükü ve günlük operasyon ise ayrışır.

Kriter Doğrudan banka POS’u Ödeme kuruluşu
Sözleşme Her bankayla ayrı Tek sözleşme, çok banka
Taksit kampanyaları Yalnız o bankanın kartları Kuruluşun anlaşmalarına bağlı
Entegrasyon Bankanın altyapı sağlayıcısına özgü API Genellikle tek, belgelenmiş REST API
Kart verisi Ortak ödeme sayfası veya doğrudan post Çoğunlukla barındırılan form veya iframe
Para transferi Bankanın valör kuralları Kuruluşun hesaba aktarım takvimi
Mutabakat Banka başına ayrı rapor Tek panel, tek rapor

Cirosu yüksek ve belirli bankalarla pazarlık gücü olan şirketler komisyon için doğrudan POS’a gider. Bedeli de vardır: her yeni banka ayrı test, ayrı hash algoritması, ayrı mutabakat raporu demektir. Üç banka, üç ayrı entegrasyon. Ödeme kuruluşu modelinde API entegrasyonu tektir; buna karşılık para hesaba kuruluşun aktarım takvimine göre geçer ve iade kuralları kuruluşun API’sinin izin verdiği kadardır.

Kart verisinin nerede girildiği PCI DSS yükünüzü belirler. Kart numarası tamamen bankanın veya kuruluşun barındırdığı sayfada ya da iframe içinde alınıyorsa genellikle en dar öz değerlendirme anketi (SAQ A) uygulanır. Kart verisi sizin sayfanızdaki bir formdan doğrudan bankaya post ediliyorsa (direct post) ödeme sayfanızın bütünlüğü de kapsama girer; bu modelde çok daha fazla gereksinim içeren SAQ A-EP söz konusu olur. Kart verisi sunucunuzdan geçiyorsa kapsam daha da genişler. Hangi anketin size düştüğünü ödeme sağlayıcınızla ve PCI Security Standards Council belgeleriyle teyit edin; tahminle karar vermeyin.

3D Secure ödeme akışı adım adım

EMV 3-D Secure, kart sahibinin kimliğini kartı çıkaran bankanın doğruladığı protokoldür. Güncel uygulamalar 3DS 2.x kullanır; banka, cihaz ve işlem verisine bakarak kullanıcıyı SMS doğrulamasına yönlendirir ya da sessiz (frictionless) onay verir. WooCommerce tarafında tipik akış şöyle işler:

  1. Müşteri ödeme sayfasında siparişi onaylar; WooCommerce siparişi pending (Ödeme bekleniyor) durumunda açar ve stok, ayarlardaki “Stoku tut” süresi boyunca ayrılır.
  2. Ödeme geçidi sınıfının process_payment() metodu sipariş numarası, tutar, para birimi, taksit sayısı, başarılı ve başarısız dönüş adresleriyle bir istek hazırlar ve mağaza anahtarıyla imzalar.
  3. Müşteri bankanın veya kuruluşun 3D sayfasına gider ve doğrulamayı tamamlar.
  4. Banka sonucu iki kanaldan bildirebilir: tarayıcı üzerinden dönüş adresine POST ve sunucudan sunucuya bildirim (callback). Hangi kanalın var olduğu sağlayıcıya göre değişir.
  5. Bazı doğrudan POS modellerinde 3D doğrulama tek başına tahsilat değildir; doğrulama başarılıysa provizyon için ikinci bir API çağrısı gerekir.
  6. Sonuç doğrulandıktan sonra sipariş processing durumuna alınır, işlem numarası siparişe yazılır, müşteri teşekkür sayfasına düşer.

Sahada en sık gördüğümüz hata beşinci adımın atlanmasıdır. Geliştirici 3D dönüşünde “başarılı” görür, siparişi ödenmiş sayar; provizyon çağrısı hiç yapılmadığı için para çekilmez.

Callback doğrulama ve sipariş durumu eşleştirme

Dönüş adresine gelen veri müşterinin tarayıcısından geçer. Güvenilir değildir. Her bildirimde en az şu kontroller yapılır:

  • İmza/hash doğrulaması: Sağlayıcının tanımladığı alanlar ve mağaza anahtarıyla hash yeniden hesaplanır, sabit zamanlı karşılaştırma (hash_equals) ile kontrol edilir.
  • Tutar ve para birimi: Bildirimdeki tutar siparişin get_total() değerine eşit olmalı. Taksit farkı uygulanıyorsa fark sipariş satırına yansıtılmış olmalı.
  • Sipariş eşleşmesi: Sağlayıcıya gönderilen referans ile bildirimdeki referans eşleşmeli, sipariş ödeme bekleyen bir durumda olmalı.
  • Tekrar (idempotency): Aynı işlem numarası ikinci kez gelirse sipariş yeniden işlenmez, yalnızca not düşülür.
  • Mümkünse sorgu API’si: Sağlayıcı işlem sorgulama servisi sunuyorsa sonuç sunucu tarafında bir kez daha sorgulanır.

WooCommerce’ta sunucudan sunucuya bildirim woocommerce_api_{ad} eylemiyle karşılanır; adres /?wc-api=ad biçimindedir. Aşağıdaki iskelet akışı gösterir; hash alanları ve sonuç kodları sağlayıcının dokümantasyonuna göre doldurulur.

add_action( 'woocommerce_api_ornek_pos', function () {
    $data  = wp_unslash( $_POST );
    $order = wc_get_order( absint( $data['order_ref'] ?? 0 ) );
    if ( ! $order ) { status_header( 404 ); exit; }

    $expected = base64_encode( hash_hmac( 'sha256', $data['order_ref'] . $data['amount'] . $data['status'], STORE_KEY, true ) );
    if ( ! hash_equals( $expected, (string) ( $data['hash'] ?? '' ) ) ) {
        $order->add_order_note( 'Geçersiz imzalı ödeme bildirimi reddedildi.' );
        status_header( 400 ); exit;
    }
    if ( $order->is_paid() ) { echo 'OK'; exit; }   // tekrar gelen bildirim

    if ( wc_format_decimal( $data['amount'], 2 ) !== wc_format_decimal( $order->get_total(), 2 ) ) {
        $order->update_status( 'on-hold', 'Tutar uyuşmazlığı, manuel kontrol gerekli.' );
        exit;
    }
    if ( 'success' === $data['status'] ) {
        $order->payment_complete( sanitize_text_field( $data['transaction_id'] ) );
    } else {
        $order->update_status( 'failed', 'Banka sonucu: ' . sanitize_text_field( $data['error_code'] ?? '' ) );
    }
    echo 'OK'; exit;
} );

payment_complete() siparişi yalnız hem sanal hem indirilebilir ürünlerden oluşuyorsa completed, diğerlerinde processing durumuna alır, işlem numarasını kaydeder ve stok düşümünü tetikler. Sipariş verisine her zaman WC_Order metotlarıyla erişin. Doğrudan post meta okuyan eski kod, yüksek performanslı sipariş depolaması (HPOS) açık mağazada boş ya da eski değer döndürür; hata vermez, sessizce yanlış çalışır.

Sağlayıcı sonuçlarını WooCommerce durumlarına şöyle bağlamanızı öneririz:

Sağlayıcı sonucu WooCommerce durumu Not
Provizyon onaylandı processing payment_complete() ile
3D doğrulama başarısız failed Müşteri tekrar deneyebilir
Tutar veya imza uyuşmazlığı on-hold Manuel inceleme
Sonuç bilinmiyor / zaman aşımı pending Sorgu API’siyle tekrar kontrol
İade edildi (tam) refunded Banka iade numarası notta

İade, iptal ve kısmi iade senaryoları

Banka tarafında iki ayrı işlem vardır. İptal, işlem gün sonuna girmeden yapılır ve provizyonu tamamen kaldırır; kart ekstresine çoğu zaman hiç yansımaz. İade ise gün sonu alınmış işlem içindir, tam veya kısmi olabilir ve tutar kart sahibine bankanın kendi süresinde geçer. Bazı sağlayıcılar ikisini tek uç noktada birleştirip tarihe göre kendisi karar verir; bazıları ayrı çağrı ister. Dokümantasyonu okumadan varsaymayın.

Geçidin supports dizisine refunds eklenip process_refund( $order_id, $amount, $reason ) metodu yazıldığında sipariş ekranındaki iade düğmesi sağlayıcı API’sini çağırır. Kontrol edilecekler:

  • Taksitli işlemde kısmi iade için sağlayıcının kuralına bakın; bazı altyapılar taksitli satışta kısmi iadeyi kısıtlar.
  • API çağrısı başarısız olursa metot WP_Error döndürmeli. Aksi halde WooCommerce iadeyi yapılmış gibi kaydeder, para ise müşteriye hiç gitmez.
  • “Manuel iade” seçeneği yalnız sipariş kaydını değiştirir, bankaya çağrı yapmaz. Banka panelinden yapılan iadeler WooCommerce’a ayrıca işlenmelidir.
  • İade tutarını ve banka iade referansını sipariş notuna yazın; mutabakatta ilk bakılan yer orasıdır.

Gün sonu mutabakatı

Mutabakat üç kaynağın aynı şeyi söylediğini doğrular: WooCommerce siparişleri, sağlayıcının işlem raporu ve banka hesabına geçen tutar. Günlük çalışan bir iş, önceki günün kayıtlarını işlem numarası üzerinden eşleştirir ve farkları listeler. Aranacak fark türleri:

  • Sağlayıcıda başarılı, WooCommerce’ta pending, failed veya cancelled olan işlemler (para alınmış ama sevk edilmeyecek sipariş).
  • WooCommerce’ta ödenmiş görünen ama sağlayıcı raporunda bulunmayan siparişler.
  • Tutar farkları: taksit vade farkı, kısmi iade, kupon sonrası tutar.
  • Panelden yapılmış ama siparişe işlenmemiş iadeler.
  • Komisyon ve valör bilgisinin muhasebe kaydıyla uyumu.

WooCommerce tarafının dökümü WP-CLI ile alınır; örneğin wp wc shop_order list --status=processing --after=2026-11-09T00:00:00 --fields=id,total,transaction_id --user=1 komutu sağlayıcı raporuyla karşılaştırılacak listeyi verir (alan adları ve parametreler WooCommerce REST API’sinin sipariş uç noktasıyla aynıdır). Sonuçları bir tabloda saklayın, fark çıktığında sorumluya bildirim gitsin. Kimse bakmıyorsa mutabakat yapılmamış sayılır. Bu kontrollerin genel tasarımı entegrasyon izleme ve mutabakat rehberinde ayrıntılı anlatılıyor.

Sık görülen ödeme hataları ve çözümleri

Ödeme alındı ama sipariş “Ödeme bekleniyor” durumunda kaldı

Konsolda ilk bakılacak yer web sunucusu ve WAF loglarıdır. Tipik nedenler: sunucudan sunucuya bildirimin WAF, Cloudflare kuralı veya IP kısıtlaması tarafından engellenmesi; bildirim adresinin sayfa önbelleğine alınması; müşterinin 3D sonrası tarayıcıyı kapatması ve sistemin yalnız tarayıcı dönüşüne güvenmesi. Çözüm: bildirim adresini önbellek ve bot korumasının dışında tutun, sağlayıcının çıkış IP’lerine izin verin, bekleyen siparişleri sorgu API’siyle periyodik kontrol eden bir zamanlanmış görev çalıştırın. Önbellek dışlamalarının nasıl yapılacağı WooCommerce cache hataları yazısında.

Banka dönüşünde müşterinin oturumu ve sepeti kayboluyor

Banka sayfasından dönüş, başka bir alan adından gelen POST isteğidir. SameSite=Lax çerezler bu istekte gönderilmez, WooCommerce oturumu görünmez. Dönüş işleyicisi oturuma değil sipariş numarası ve sipariş anahtarına (order_key) dayanmalı; işlem bitince kullanıcı GET ile teşekkür sayfasına yönlendirilmeli.

Ödeme alınmış sipariş otomatik iptal edildi

“Stoku tut (dakika)” süresi dolunca ödenmemiş siparişler iptal edilir. Müşteri 3D sayfasında uzun beklerse banka onayı iptal edilmiş siparişe gelir. Callback işleyicisi bu durumu tanımalı; siparişi kendiliğinden geri açmak yerine on-hold durumuna alıp stoku kontrol ettirmeli veya iade sürecini başlatmalıdır.

Aynı sipariş iki kez tahsil edildi

Ödeme düğmesine çift tıklama ya da geri tuşuyla yeniden deneme, aynı sipariş referansıyla iki istek üretebilir. Her denemeye ayrı bir işlem referansı verin, ödenmiş siparişte yeni ödeme isteği oluşturmayın, mutabakatta aynı siparişe bağlı birden fazla başarılı işlemi ayrıca raporlayın.

Canlıya almadan önce test ortamında şu senaryoları tek tek deneyin: başarılı, başarısız, zaman aşımı, kısmi iade, tekrar gelen bildirim. Denenmeyen senaryo canlıda patlar. Mağazanın genel kurgusu ve sağlayıcı seçimi için WooCommerce e-ticaret çözümleri sayfasına bakabilirsiniz; sipariş sonrası lojistik akışı WooCommerce kargo entegrasyonu rehberinin konusu.

Sık sorulan sorular

Sanal POS için hazır eklenti mi kullanılmalı, özel geliştirme mi?

Sağlayıcının resmi veya yaygın kullanılan eklentisi callback doğrulaması, iade desteği ve HPOS uyumluluğu sağlıyorsa önce onu kullanın. Özel geliştirme; birden fazla bankayla taksit yönlendirmesi, ERP’ye özel referans alanları veya eklentinin desteklemediği bir iade modeli gerektiğinde anlamlıdır.

3D Secure olmadan ödeme almak mümkün mü?

Bazı sağlayıcılar belirli risk kurallarıyla 3D Secure olmadan işleme izin verir, ancak bu durumda itiraz ve dolandırıcılık riskinin büyük kısmı işyerine kalır. Kurumsal mağazada 3D Secure varsayılan olmalı, istisnalar sağlayıcıyla yazılı olarak tanımlanmalıdır.

İptal ile iade arasındaki fark nedir?

İptal, işlem gün sonuna girmeden yapılır ve provizyonu tamamen kaldırır. İade, gün sonu alınmış işlem için yapılır, tam veya kısmi olabilir ve tutar kart sahibine bankanın kendi süresinde geçer. Hangisinin uygulanacağını sağlayıcının API kuralları belirler.

Mutabakat ne sıklıkla yapılmalı?

Her gün. Önceki günün WooCommerce siparişleri sağlayıcı raporuyla işlem numarası üzerinden eşleştirilir, farklar listelenir ve sorumluya bildirilir. Hesaba geçen tutar ve komisyon kontrolü ise sağlayıcının aktarım takvimine göre ayrıca yapılır.

Destek

Bu konuda destek ya da keşif için bize ulaşın.

İletişim formu
[email protected]

Eretek Web

Kurumsal web siteleri, WordPress ve CMS platformları, intranet ve SharePoint portalları, doküman yönetimi ile form ve onay süreçlerini kuruyor, güvenli ve güncel tutuyoruz.

Bilgi Merkezi

Diğer yazılar