VibeFox Midtrans for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

PHP: 8.0 veya üzeri. Modül, eski PHP sürümlerinde kurulmayı reddeder.

Para birimi: Endonezya Rupiahı (IDR). Midtrans yalnızca IDR cinsinden tahsilat yapar; bu nedenle ödeme yöntemi yalnızca sepet para birimi IDR olduğunda sunulur. Para birimi dönüşümü yoktur. Mağazanızda IDR para birimi yoksa, International > Localization bölümünden ekleyin.

Midtrans hesabı: Midtrans Dashboard > Settings > Access Keys bölümündeki Server Key'e ihtiyacınız var; hem sandbox panelinde hem de canlı panelde. 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 bir alan adında çalışır.

Kurulum

1. Back office'te Modules > Module Manager bölümüne gidin ve Upload a module düğmesine tıklayın. Modülün ZIP dosyasını seçin.

2. Yükleme tamamlandığında Configure düğmesine tıklayın veya daha sonra modül listesinde VibeFox Midtrans Payment Gateway öğesini bulup Configure düğmesine tıklayın.

3. VibeFox lisans anahtarınızı Configure sayfasının üstündeki lisans bloğunda License key alanına girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

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

5. Enable/Disable seçeneğini açın ve Save düğmesine tıklayın. Sandbox'ta test edin, ardından Environment seçeneğini Production'a çevirin.

Kurulumda modül iki sipariş durumu oluşturur: Awaiting Midtrans payment ve Midtrans payment on hold. PrestaShop, tüm para birimleri, ülkeler ve müşteri grupları için yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünden sınırlayabilirsiniz. Modül, IDR para birimi için izinli kalmalıdır.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Her bölümün kendi Save düğmesi vardır ve bu düğme tüm sayfayı kaydeder. Alanların üstünde sayfa, seçili ortamın Server Key'i eksikse (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve mağazanın varsayılan para birimi IDR değilse sizi uyarır; Sandbox seçiliyken Sandbox mode: payments are simulated, no real money is charged. ifadesini gösterir.

Midtrans

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

Title: müşterilere ödeme sayfasında gösterilen ödeme yöntemi başlığı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Midtrans. Zorunlu.

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

Server Key'i Midtrans Dashboard > Settings > Access Keys bölümünden kopyalayın. Bölümde canlı panele ve sandbox paneline 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. Ödemeler, iade ve bildirimler için yapıldıkları ortamı korur. Varsayılan: Sandbox.

Sandbox: test için, gerçek para olmadan.

Production: canlı ödemeler.

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

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

Kaydedilmiş anahtarlar bir daha gösterilmez. Alan boş kalır ve Saved — leave empty to keep it. ifadesini gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Clear saved keys: bir anahtarı işaretleyip Save düğmesine tıklayarak kaldırın. Boş bir alan, kaydedilmiş değeri korur.

Ödeme bildirimi URL'si

Bildirim, mağazanıza bir ödemenin yapıldığını söyler. Notification URL alanı kullanılacak URL'yi gösterir. Okunabilir URL'lerle şöyle görünür: https://your-shop/module/wcp_midtrans_payment_gateway/webhook; başında /en/ gibi bir dil kodu da olabilir. URL'yi ayarların gösterdiği gibi birebir kopyalayın ve kullandığınız sandbox ile canlı panelindeki Midtrans Dashboard > Settings > Payment > Notification URL alanına yapıştırın. URL'yi 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 bildirim, Server Key'lerinizden biriyle oluşturulmuş geçerli bir imza taşımalı ve anahtarın ortamı ödemenin ortamıyla eşleşmelidir. Geçerli imzası olmayan bildirimler reddedilir. Bu durumda durum Midtrans durum API'sinden yeniden okunur. Modül şu Midtrans işlem durumlarını işler:

settlement, capture (accepted): ödeme yapıldı. Tutar (tam rupi cinsinden) ve para birimi sepetle eşleşirse sipariş ödenmiş olarak oluşturulur.

capture (challenge): Midtrans'in sahtecilik tespiti tarafından işaretlenen kart ödemesi. Midtrans panelinde onaylayana veya reddedene kadar sipariş Midtrans payment on hold durumuna geçer.

pending: müşteri ertelenmiş bir yöntem seçti (sanal hesap, mini market) ve henüz ödeme yapmadı. Sipariş Awaiting Midtrans payment durumunda oluşturulur.

expire, cancel: ödenmemiş işlemin süresi doldu veya iptal edildi. Bekleyen bir sipariş, ödeme yöntemi ne olursa olsun Canceled durumuna geçer. Sipariş yoksa yalnızca deneme kapatılır ve müşteri sepeti yeniden ödeyebilir.

deny: ödeme reddedildi. Bekleyen bir sipariş Payment error durumuna geçer.

failure: ödeme başarısız oldu. Bekleyen bir sipariş Payment error durumuna geçer.

refund, partial_refund: Midtrans panelinde yapılan bir iade siparişe kaydedilir.

Bildirim URL'si olmadan sipariş yalnızca müşteri ödemeden sonra mağazaya döndüğünde oluşturulur; daha sonra yapılan ertelenmiş bir ödeme ise müşteri geri dönene kadar görülmez.

Ödeme ayarları

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

Status after payment: onaylanmış bir ödemeden sonraki sipariş durumu.

Processing (default): Payment accepted, ödenmiş siparişler için PrestaShop'un standart durumu.

Completed: ödenmiş her sipariş Delivered olur.

On hold: ödenmiş her sipariş, manuel incelemeniz için Midtrans payment on hold durumuna geçer. Ödeme siparişte kayıtlı kalır.

Payment page expiry (minutes): müşterinin ne kadar süre ödeme yapabileceği (Snap sayfası, sanal hesap vb.). Boş bırakın veya Midtrans varsayılanı için 0 girin. Tam sayı dakika olmayan bir değer, kaydederken hata verilerek reddedilir.

Order ID prefix: Midtrans'e gönderilen numaranın başına eklenir; böylece birden çok mağaza tek bir Midtrans hesabını paylaşabilir. Numara, sepet ID'si ile bir zaman damgasından oluşur, örneğin WC-123-1700000000. Yalnızca harfler, rakamlar ve - _ . ~ karakterleri, en fazla 20 karakter; diğer karakterler kaydederken silinir. Diğer mağazaların bildirimleri yok sayılır. Varsayılan: WC-.

Gelişmiş

Debug log: API çağrılarını ve bildirimleri modül klasöründeki logs/midtrans_p_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar her zaman kaydedilir. Anahtarlar ve müşteri verileri hiçbir zaman kaydedilmez. Varsayılan: kapalı.

Log: günlüğün boyutunu ve son kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Delete data on uninstall: açıksa modül kaldırıldığında modül ayarları ve günlük silinir. Siparişler, Midtrans ödeme referansları ve iadeler ile modülün sipariş durumları her zaman korunur; böylece eski siparişler yeniden kurulumdan sonra da iade edilebilir. Varsayılan: kapalı.

Ödeme sayfası

Ödeme adımında müşteri ödeme yöntemini seçer (varsayılan olarak Midtrans) ve onaylar. Modül, sepet tutarı için tam rupi cinsinden bir Midtrans Snap işlemi oluşturur; sipariş satırları, kargo, indirimler, hediye paketi, vergi ve müşterinin fatura ve teslimat bilgileriyle birlikte, ve müşteriyi Midtrans ödeme sayfasına gönderir. Orada müşteri, Midtrans hesabınızda etkin olan herhangi bir yöntemi seçer. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Dönüş bağlantısı tek başına bir siparişi asla ödenmiş olarak işaretlemez: sipariş yalnızca Midtrans onayladığında — imzalı bildirimle veya müşteri geri döndüğünde Midtrans durum API'sine yapılan bir sorguyla — ödenmiş olarak işaretlenir. Sipariş bu noktada oluşturulur ve müşteri, kullanılan ödeme yöntemiyle birlikte standart sipariş onay sayfasını görür. Ertelenmiş bir ödemede sayfa şunu gösterir: We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Ödeme yapılmadan kapatılan bir sipariş için: Your Midtrans payment was not completed. Please contact us about this order. Müşteri geri döndüğünde Midtrans'e ulaşılamazsa, Payment confirmation sayfası şunu gösterir: We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. ve bir Check again düğmesi.

Müşteri Snap sayfasından ödeme yapmadan ayrıldıysa, ödeme sayfasına The Midtrans payment was not completed. You can try again below. mesajıyla döner. Ödeme reddedildiyse veya süresi dolduysa mesaj şöyledir: Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Sepet korunur. Müşteri tekrar ö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'te süresi dolmuş olarak kapatılır. Önceki Snap bu arada ödenmişse sipariş oluşturulur ve yeni bir işlem yapılmaz. Sipariş zaten varsa ve ödeme yapılmadan kapatılmışsa mesaj şöyledir: Your Midtrans payment was declined or has expired. Please place a new order or contact us.

Midtrans ödemeyi başlatamazsa müşteri kısa bir mesajla ödeme sayfasında kalır: 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 ile) veya Midtrans'in belirttiği neden. Teknik neden günlüğe yazılır. IDR olmayan bir sepet Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. mesajını gösterir.

Bildirim, mağaza bakım modundayken de çalışır ve mağazanızın ülke kısıtlamasıyla engellenmez.

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

Siparişler ve iadeler

Sipariş durumları

No order yet: müşteri Midtrans'e yönlendirildi ve ödeme yapmadı ya da Midtrans henüz ödemeyi onaylamadı. Yalnızca sepet mevcut.

Awaiting Midtrans payment: müşteri ertelenmiş bir yöntem (sanal hesap, mini market) seçti ya da tamamlanmamış bir kart ödemesi başlattı. Midtrans ödemeyi bildirdiğinde sipariş ödenmiş olur.

Payment accepted, Delivered veya Midtrans payment on hold: ödeme onaylandı. Durum Status after payment ayarını izler. Ödeme, Midtrans işlem kimliğiyle kaydedilir ve bir not ödeme yöntemini ve Midtrans sipariş kimliğini gösterir.

Midtrans payment on hold: bir kart ödemesi sahtecilik incelemesindeyse (challenge, henüz kaydedilmiş bir ödeme yok), ödenen tutar veya para birimi siparişle eşleşmediyse (sipariş ödenmiş olarak işaretlenmez) veya iptal edilmiş bir sipariş için ödeme geldiyse (sipariş otomatik olarak yeniden açılmaz) da bu durum ayarlanır. Not nedenini açıklar. Siparişi kontrol edin, ardından işleyin veya ödemeyi iade edin.

Canceled: ödenmemiş işlemin süresi doldu veya iptal edildi. Ödenmemiş bir Midtrans siparişini kendiniz iptal ederseniz, bekleyen Midtrans işlemi (örneğin verilmiş bir sanal hesap) süresi dolmuş olarak kapatılır ve artık ödenemez.

Payment error: ödeme başarısız oldu veya incelemedeki bir kart ödemesi reddedildi.

Refunded: ödemenin tamamı iade edildi.

Zaten ödenmiş bir sipariş için ikinci bir ödeme gelirse sipariş değişmez. Bir not, ikinci ödemeyi Midtrans panelinde iade etmenizi ister. İade edilmiş bir sipariş için yapılan ödeme yalnızca bir not ekler.

Midtrans ödeme bloğu

Sipariş sayfasında, Midtrans sipariş kimliği, işlem kimliği (ödemenin ortamındaki Midtrans panelinde işleme bağlı), ödeme yöntemi, durum, ödenen ve iade edilen tutar, sandbox ödemeleri için bir Sandbox rozeti, iade geçmişi ve siparişin Midtrans notes bölümünü içeren bir Midtrans payment bloğu gösterilir.

İadeler

Midtrans payment bloğunda tutarı girin (henüz iade edilmemiş tutar otomatik doldurulur), isteğe bağlı olarak bir neden yazın ve Refund via Midtrans düğmesine tıklayın. Refund this amount through Midtrans? This cannot be undone. sorusunu onaylayın. Tam ve kısmi iadeler tam rupi cinsinden desteklenir; ondalık içeren bir tutar reddedilir. Siparişleri düzenleme yetkisine sahip olmanız gerekir. Sipariş sonradan düzenlenmiş olsa bile Midtrans'in gerçekte tahsil ettiği tutara kadar iade yapabilirsiniz. İade, ödemenin yapıldığı ortamda gönderilir; bu nedenle o ortamın Server Key'i tanımlı olmalıdır. Midtrans, API iadelerine yalnızca belirli ödeme yöntemleri ve işlem durumları için izin verir (örneğin tahsil edilmiş kart ödemeleri, GoPay, QRIS veya ShopeePay). Midtrans iadeyi kabul etmezse blok hatayı gösterir ve hiçbir iade kaydedilmez; bu durumda Midtrans panelinden iade yapın. Başarılı bir iade iade geçmişine ve notlara eklenir. Tam iade siparişi Refunded durumuna getirir. Kısmi iade durumu değiştirmez. İadeler, Midtrans ödemeyi tahsil edildi olarak bildirdikten sonra kullanılabilir.

Modül kredi notası oluşturmaz. Sipariş sayfasındaki PrestaShop'un standart iade düğmeleri Midtrans üzerinden para geri göndermez.

Midtrans panelinde yapılan iadeler bildirim yoluyla gelir ve Refunded in the Midtrans dashboard nedeniyle otomatik olarak iade geçmişine eklenir. Ödemenin tamamı orada iade edildiğinde sipariş Refunded durumuna geçer.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Midtrans Payment Gateway lisans bloğu, Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure sayfasının ilk bloğudur ve ayarların üstünde yer alır. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu son tarih ve alan adınızı) ve şu düğmeleri gösterir: durumu yeniden kontrol etmek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu mağazadan kaldırmak için Remove key. Bunların altında Product: presta-payment-midtrans satırı ve vibefox.net hesabınızı açan Manage licenses and domains in your account bağlantısı bulunur. Anahtarı yalnızca modül için Configure yetkisi olan çalışanlar değiştirebilir. Bloğun metinleri yönetim paneli dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini gösterir; örneğin Key not found, This key belongs to another product, Domain limit reached veya tarihli License expired on. Mağaza adresi değiştikten sonra veya hesabınızda bir alan adı yuvasını serbest bıraktıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa modül son bilinen durumla çalışmaya devam eder.

Bir anahtar bir alan adında çalışır: ana mağazanın alan adında, çoklu mağaza kurulumunda da. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan 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. PrestaShop vitrini back office'e giriş yaptığınızı bilmez; bu nedenle ödeme yöntemi sizin için de gizlenir: modülü bir anahtar satın almadan önce kurabilirsiniz, ama ödeme sayfasında test edemezsiniz. Modules > Module Manager sayfasında Alerts sekmesinde bir hatırlatma görünür. Mevcut siparişler etkilenmez: zaten başlatılmış ödemeler yine onaylanır ve iadeler çalışır.

Bir lisans süresi dolduğunda modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Back office'te çalışırken durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün her gün, ardından haftada bir. Cron işi gerekmez. Modülü kaldırmak veya sıfırlamak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

Midtrans does not appear at checkout: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu ve seçili Environment için Server Key bulunduğunu kontrol edin. Sepet para biriminin IDR olduğunu doğrulayın. Payment > Preferences bölümünde modülün IDR, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin. Ayarlar sayfası, anahtar eksikse veya mağaza para birimi IDR değilse uyarı gösterir.

The payment went through, but no order was created: bildirim çalışmıyor. Kullandığınız ortamın (sandbox veya canlı) Midtrans panelinde ödeme bildirimi URL'sinin tanımlı olduğunu, Notification URL alanında gösterilen URL ile birebir aynı olduğunu ve erişilebilir olduğunu kontrol edin: 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. Sipariş, müşteri ödemeden sonra mağazaya döndüğünde de oluşturulur.

Notification answers Invalid signature: bildirim, Sandbox veya Production Server Key'iniz ile imzalanmamış. Ayarlardaki anahtarların, bildirimleri gönderen panelle aynı Midtrans hesabına ait olduğunu kontrol edin.

Notification answers Server key not configured: hiçbir Server Key tanımlı değil. Ayarlara girin; Midtrans bildirimi yeniden deneyecektir.

Notification answers Order not found — ignored: Midtrans sipariş kimliği bu mağaza tarafından verilmemiş; örneğin aynı Midtrans hesabındaki başka bir mağaza tarafından verilmiş. Her mağazaya farklı bir Order ID prefix verin.

Notification answers Environment mismatch — ignored: bildirim, ödemenin yapıldığı ortamın dışındaki ortamın anahtarıyla imzalanmış.

Notification answers Verification failed, please retry: Midtrans durum API'sine ulaşılamadı. Midtrans bildirimi yeniden deneyecektir.

Notification answers Busy, please retry: sepet aynı anda başka bir istek tarafından güncelleniyordu veya sipariş oluşturulamadı (örneğin modül devre dışı). Midtrans bildirimi yeniden deneyecektir. Nedeni görmek için günlüğe bakın.

The order is Midtrans payment on hold: bloktaki Midtrans notes bölümünü okuyun. Kart ödemesi sahtecilik incelemesinde, ödenen tutar veya para birimi siparişle eşleşmiyor ya da ödeme sipariş iptal edildikten sonra geldi.

The customer sees an error when choosing Midtrans: modül sayfasındaki Log alanına bakın; hatalar her zaman kaydedilir. Yanlış bir Server Key, Midtrans ödemelerinin geçici olarak kullanılamadığına dair mesajı gösterir.

Refund fails: ödeme yöntemi veya işlem durumu API iadelerine izin vermiyor; Midtrans panelinden iade edin, iade siparişe otomatik olarak kaydedilecektir. Mesaj, siparişin ödendiği ortam için bir Server Key tanımlı olmadığını söylüyorsa, bu anahtarı girin ve yeniden deneyin.

Geliştiriciler, actionWcpMidtransSnapPayload kancasıyla Midtrans'e gönderilen verileri değiştirebilir; sipariş kimliği ve tutar değiştirilemez.

Kaldırma

Modules > Module Manager bölümüne gidin, VibeFox Midtrans Payment Gateway yanındaki menüyü açın ve Uninstall seçeneğini seçin. Bu modülün lisans anahtarı ve lisans durumu her zaman silinir. Delete data on uninstall açıksa modül ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki bir yeniden kurulum için saklanır. Siparişlerin Midtrans ödeme referansları ve iadeleri ile Awaiting Midtrans payment ve Midtrans payment on hold sipariş durumları her zaman korunur; böylece daha önce ödenmiş siparişler yeniden kurulumdan sonra da iade edilebilir. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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