VibeFox Midtrans for WooCommerce — Yardım

Gereksinimler

WordPress: 6.0 veya üzeri.

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

PHP: 8.0 veya üzeri.

Mağaza para birimi: Endonezya Rupiahı (IDR). Diğer para birimlerinde ödeme yöntemi ödeme sayfasında gizlenir. Para birimi dönüşümü yoktur.

Midtrans hesabı: Midtrans Dashboard > Settings > Access Keys bölümündeki Server Key'e ihtiyacınız vardır; bu anahtar sandbox panelinde ve canlı panelde ayrı ayrı bulunur. Yalnızca Server Key kullanılır. Snap Redirect için Client Key gerekmez. Ödeme yöntemlerinin kendisi (GoPay, QRIS, sanal hesaplar ve diğerleri) Midtrans hesabınızda etkinleştirilir.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek 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. Ayrıca wcp_midtrans_payment_gateway klasörünü FTP ile /wp-content/plugins/ dizinine yükleyebilirsiniz.

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

3. Mağaza para birimini Endonezya Rupiahı (IDR) olarak ayarlayın.

4. Ayarları açın: WooCommerce > Settings > Payments > Midtrans > Manage veya Eklentiler sayfasında eklenti adının altındaki Settings bağlantısına tıklayın.

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

6. Server Key'leri girin ve ödeme bildirimi URL'sini Midtrans paneline kopyalayın (bkz. Yapılandırma).

7. Enable/Disable seçeneğini açın. Sandbox'ta test edin, ardından Environment ayarını Production'a çevirin.

Yapılandırma

Tüm ayarlar tek bir sayfadadır: WooCommerce > Settings > Payments > Midtrans. Alanların üstünde sayfa, seçili ortamın Server Key'i eksik olduğunda (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve mağaza para birimi IDR değilken sizi uyarır; Sandbox seçiliyken de Sandbox mode: payments are simulated, no real money is charged. mesajını gösterir. Ödeme yöntemleri listesinde Midtrans, bir Server Key girilene kadar kurulum gerektiren olarak işaretlenir ve Sandbox'ta Test mode gösterir.

Genel

Enable/Disable: Enable Midtrans payments ödeme yöntemini açar veya kapatır. Varsayılan: off.

Title: ödeme sayfasında müşterilere gösterilen ödeme yöntemi başlığı. Varsayılan: Midtrans.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. Sandbox'ta SANDBOX MODE: no real money is charged. satırı eklenir.

API kimlik bilgileri

Midtrans Dashboard > Settings > Access Keys bölümünden Server Key'i kopyalayın. Bölümde canlı ve sandbox panellerine bağlantılar bulunur.

Environment: yeni ödemelerin kullandığı Midtrans ortamı. Değiştirildiğinde seçili ortamın anahtarı ve API'si kullanılır. Siparişler, iadeler ve bildirimler için ödendikleri ortamı korur. Varsayılan: Sandbox.

Production Server Key: Mid-server- ile başlar. Gizli tutun.

Sandbox Server Key: SB-Mid-server- ile başlar.

Ödeme bildirimi URL'si

Bildirim, mağazanıza bir ödemenin yapıldığını iletir. Bölüm kullanılacak URL'yi gösterir. Şuna benzer görünür: https://your-site/wc-api/midtrans_p_callback/. Bunu, kullandığınız sandbox ve canlı Midtrans panelindeki Midtrans Dashboard > Settings > Payment > Notification URL alanına yapıştırın. URL'yi bir tarayıcıda açarsanız kısa bir açıklama görünür; böylece erişilebilir olduğunu kontrol edebilirsiniz. Midtrans panelindeki Test notification URL düğmesine de yanıt verilir.

Her bildirimin, Server Key'lerinizden biriyle oluşturulmuş geçerli bir imza taşıması gerekir ve anahtarın ortamı siparişin ortamıyla eşleşmelidir. Geçerli imzası olmayan bildirimler reddedilir. Durum daha sonra Midtrans durum API'sinden yeniden okunur. Eklenti şu Midtrans işlem durumlarını işler:

Bildirim URL'si olmadan bir sipariş yalnızca müşteri ödeme yaptıktan sonra mağazaya döndüğünde onaylanır.

Ödeme ayarları

Midtrans yalnızca IDR cinsinden tahsilat yapar ve tutarlar tam rupi olarak gönderilir. Sipariş kalemleri yuvarlanmış toplamla eşleşmezse Midtrans'a bir Rounding adjustment satırı gönderilir.

Status after payment: onaylanmış bir ödemeden sonraki sipariş durumu. Durum tek adımda ayarlanır; müşteriye çift e-posta gönderilmez.

Payment page expiry (minutes): müşterinin ne kadar süre ödeme yapabileceği (Snap sayfası, sanal hesap vb.). Midtrans varsayılanı için boş bırakın veya 0 yazın.

Order ID prefix: Midtrans'a gönderilen sipariş numarasına eklenir; böylece birden çok mağaza tek bir Midtrans hesabını paylaşabilir. Yalnızca harf, rakam ve - _ . ~, en fazla 20 karakter; diğer karakterler kaydedilirken silinir. Diğer mağazaların bildirimleri yok sayılır. Varsayılan: WC-.

Gelişmiş

Debug log: Log API calls and notifications seçeneği WooCommerce > Status > Logs bölümüne, wcp_midtrans_payment_gateway kaynağıyla yazar. Hatalar her zaman kaydedilir. Anahtarlar ve müşteri verileri hiçbir zaman kaydedilmez. Varsayılan: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. Varsayılan: off.

Ödeme

Müşteri ödeme yöntemini seçer (varsayılan olarak Midtrans) ve siparişi verir. Eklenti, sipariş toplamı için tam rupi cinsinden bir Midtrans Snap işlemi oluşturur; sipariş kalemleri, kargo, vergi ve müşterinin fatura ve teslimat bilgileriyle birlikte müşteriyi Midtrans ödeme sayfasına yönlendirir. Orada müşteri, Midtrans hesabınızda etkin olan herhangi bir yöntemi seçer.

Ödemeyi yaptıktan sonra müşteri mağazanızın sipariş alındı sayfasına döner. Dönüş bağlantısı tek başına hiçbir siparişi ödenmiş olarak işaretlemez: eklenti Midtrans durum API'sini sorgular ve sipariş yalnızca Midtrans onayladığında ödenmiş olarak işaretlenir. Ödeme onaylanmadığı sürece sayfa We are waiting for Midtrans to confirm your payment. ... mesajını gösterir. Sayfada ayrıca kullanılan ödeme yöntemi de yer alır.

Ödeme tamamlanmadıysa müşteri The Midtrans payment was not completed. You can try again below. mesajıyla Pay for order sayfasına yönlendirilir. Ödeme reddedildiyse veya süresi dolduysa mesaj Your Midtrans payment was declined or has expired. ... şeklindedir. Müşteri yeniden ödeme yaptığında, aynı tutar için kullanılmamış veya bekleyen bir Snap yeniden kullanılır. Tutar değiştiyse bekleyen işlem önce Midtrans'ta süresi dolmuş olarak sonlandırılır. Önceki Snap bu arada ödendiyse sipariş onaylanır ve yeni bir işlem oluşturulmaz.

Midtrans ödemeyi başlatamazsa müşteri Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (örneğin yanlış bir Server Key nedeniyle) mesajını veya Midtrans'ın bildirdiği nedeni görür. Teknik neden sipariş notlarına eklenir.

Ödeme yöntemi klasik ödeme sayfasında, Ödeme bloğunda ve Pay for order sayfasında çalışır. WooCommerce yüksek performanslı sipariş depolama (HPOS) ile uyumludur.

Eklenti yalnızca Snap Redirect kullanır. Snap açılır penceresi, sitenizde kart formu, kayıtlı kart veya tek tıkla ödeme, taksit ve promosyon ayarı (ödeme yöntemlerini Midtrans panelinde yapılandırın) ve WooCommerce Subscriptions yoktur. Kart ödemeleri hemen tahsil edilir; ayrı yetkilendirme ve tahsilat yoktur.

Siparişler ve iadeler

Sipariş durumları

Pending payment: müşteri Midtrans'a yönlendirildi ve henüz bir ödeme yöntemi seçmedi.

On hold: müşteri ertelenmiş bir yöntem seçti ve henüz ödeme yapmadı, kart ödemesi dolandırıcılık incelemesinde (challenge) ya da ödenen tutar veya para birimi siparişle eşleşmiyor. İptal edilmiş bir siparişe ödeme geldiğinde de Beklemede durumu ayarlanır; sipariş otomatik olarak yeniden açılmaz. Sipariş notu bunu açıklar.

Processing, Completed or On hold after payment: ödeme onaylandı. Durum Status after payment ayarını izler. Sipariş notunda ödeme yöntemi ve Midtrans kimlikleri gösterilir. İşlem kimliği Midtrans işlem kimliğidir ve sipariş ekranında siparişin ortamındaki Midtrans paneline giden bir bağlantı olarak görünür.

Failed: ödeme başarısız oldu veya challenge aşamasındaki bir kart ödemesi reddedildi.

Cancelled: ödenmemiş işlemin süresi doldu veya iptal edildi. Stok geri verilir. WooCommerce'te ödenmemiş bir Midtrans siparişini iptal ettiğinizde (ya da ödenmemiş sipariş zamanlayıcısı bunu yaptığında), bekleyen Midtrans işlemi, örneğin verilmiş bir sanal hesap, süresi dolmuş olarak sonlandırılır ve artık ödenemez.

Zaten ödenmiş bir siparişe ikinci bir ödeme gelirse sipariş bir daha değiştirilmez. Bir notta ikinci ödemeyi Midtrans panelinden iade etmeniz istenir. İade edilmiş bir siparişe gelen ödeme yalnızca bir not ekler.

İadeler

Siparişi açın, Refund düğmesine tıklayın, tutarı girin ve Refund via Midtrans düğmesine tıklayın (düğme Title ayarınızı gösterir). Tam ve kısmi iadeler tam rupi cinsinden desteklenir; ondalıklı bir tutar reddedilir. İade, siparişin ödendiği ortamda gönderilir; bu nedenle o ortamın Server Key'i girilmiş olmalıdır. Midtrans, API üzerinden iadeyi yalnızca bazı ödeme yöntemleri ve işlem durumları için kabul eder (örneğin mutabakatı tamamlanmış kart, GoPay, QRIS veya ShopeePay ödemeleri). Midtrans iadeyi kabul etmezse WooCommerce hatayı gösterir ve hiçbir iade kaydedilmez; bu durumda Midtrans panelinden iade yapın. Başarılı bir iade sipariş notlarına eklenir.

Midtrans panelinde yapılan iadeler bildirim yoluyla gelir ve Refunded in the Midtrans dashboard nedeniyle otomatik olarak WooCommerce iadeleri olarak kaydedilir.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu WooCommerce > Settings > Payments > Midtrans sayfasının üstündedir. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Blok 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, 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 tek bir alan adında çalışır. Anahtarın bir siteden kaldırılması alan adı hakkını serbest bırakmaz. Hakkı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar yoksa Midtrans, ö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) etiketiyle 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: başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Bir lisansın 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

Midtrans ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve seçili Environment için Server Key girildiğini kontrol edin. Mağaza para biriminin (veya Pay for order sayfasındaki sipariş para biriminin) IDR olduğunu doğrulayın. Ayarlar sayfası bu sorunların her biri için uyarı gösterir.

Ödeme geçti ama sipariş Pending payment durumunda kalıyor: bildirim çalışmıyor. Kullandığınız ortamın (sandbox veya canlı) Midtrans panelinde ödeme bildirimi URL'sinin ayarlı ve erişilebilir olduğunu kontrol edin: URL'yi bir tarayıcıda açın, kısa bir açıklama görünmelidir. Bildirimleri görmek için Debug log seçeneğini açın. Müşteri ödeme yapıp mağazaya döndüğünde de sipariş onaylanır.

Bildirim Invalid signature yanıtı veriyor: bildirim, Sandbox veya Production Server Key'inizle imzalanmamış. Ayarlardaki anahtarların, bildirimleri gönderen panelle aynı Midtrans hesabına ait olduğunu kontrol edin.

Bildirim Server key not configured yanıtı veriyor: hiçbir Server Key ayarlı değil. Ayarlara girin; Midtrans bildirimi yeniden dener.

Bildirim Order not found — ignored yanıtı veriyor: Midtrans sipariş kimliği bu mağazanın bir siparişine ait değil; örneğin aynı Midtrans hesabındaki başka bir mağazadan gelmiştir. Her mağazaya farklı bir Order ID prefix verin.

Bildirim Environment mismatch — ignored yanıtı veriyor: bildirim, siparişin ödendiği ortamdan farklı bir ortamın anahtarıyla imzalanmış.

Bildirim Verification failed, please retry yanıtı veriyor: Midtrans durum API'sine ulaşılamadı. Midtrans bildirimi yeniden dener.

Sipariş On hold durumunda: sipariş notunu okuyun. Müşteri ertelenmiş bir ödemeyi tamamlamamış, kart ödemesi dolandırıcılık incelemesinde olabilir veya ödenen tutar ya da para birimi siparişle eşleşmiyor olabilir.

Müşteri sipariş verirken bir hata görüyor: sipariş notlarını açın veya Debug log seçeneğini açıp WooCommerce > Status > Logs bölümünde wcp_midtrans_payment_gateway kaynağına bakın. IDR dışında bir sipariş Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. mesajını gösterir.

İade başarısız oluyor: ödeme yöntemi veya işlem durumu API üzerinden iadeye izin vermiyor; Midtrans panelinden iade yapın, iade WooCommerce'te otomatik olarak kaydedilir. Mesaj, siparişin ödendiği ortam için Server Key yapılandırılmadığını söylüyorsa bu anahtarı girip yeniden deneyin.

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ızdan bir hak 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şılamazsa eklenti son bilinen durumla çalışmaya devam eder.

Kaldırma

Eklentiyi devre dışı bırakmak tüm verileri korur. Kaldırmak için eklentiyi devre dışı bırakıp Plugins sayfasından silin. Bu eklentinin lisans anahtarı ve lisans durumu her zaman silinir. Ağ geçidi ayarları ve günlükler yalnızca Delete data on uninstall seçeneği açıksa silinir. Aksi halde daha sonraki bir yeniden kurulum için saklanır. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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