VibeFox Xendit for PrestaShop — Yardım

Gereksinimler

PrestaShop: 8.0 ila 9.x.

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

Mağaza para birimi: IDR, PHP, VND, THB, MYR, USD veya SGD. Diğer sepet para birimleri için ödeme yöntemi gösterilmez. Hangi ödeme kanallarının ve para birimlerinin gerçekten kullanılabilir olduğu Xendit hesabınıza bağlıdır.

Xendit hesabı: test modu için Money-in (faturalar) izni yazma yetkisine sahip bir gizli API anahtarına, canlı mod için ise başka bir anahtara ve her modun webhook doğrulama jetonuna ihtiyacınız vardır (bkz. Yapılandırma). Yalnızca gizli anahtarlar ve doğrulama jetonları kullanılır. Müşteri, Xendit tarafından barındırılan fatura sayfasında ödeme yaptığı için herkese açık anahtar gerekmez.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek bir alan adında çalışır.

Kurulum

1. Yönetim panelinde Modules > Module Manager sayfasına gidin ve Upload a module seçeneğine tıklayın. Modülün ZIP dosyasını seçin.

2. Yükleme tamamlandığında Configure seçeneğine tıklayın ya da daha sonra modül listesinde VibeFox Xendit Payment Gateway modülünü bulup Configure seçeneğine 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. Xendit gizli anahtarlarınızı yapıştırın, Xendit Dashboard'da webhook URL'sini ayarlayın ve doğrulama jetonlarını yapıştırın (bkz. Yapılandırma).

5. Enable/Disable seçeneğini açın ve Save seçeneğine tıklayın. Test modunda deneme siparişi verin, ardından gerçek ödemeleri kabul etmek için Test Mode seçeneğini kapatın.

Kurulumda modül Xendit payment on hold sipariş durumunu oluşturur. PrestaShop, tüm para birimleri, ülkeleri ve müşteri gruplarını kapsayan yeni bir ödeme modülü sunar. Bunları Payment > Preferences bölümünden sınırlayabilirsiniz.

Yapılandırma

Tüm ayarlar modül sayfasındadır: Modules > Module Manager > VibeFox Xendit 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ündeki bir kutu etkin modu gösterir: TEST MODE (faturalar test gizli anahtarıyla oluşturulur ve gerçek para tahsil edilmez) veya LIVE MODE (faturalar canlı gizli anahtarla oluşturulur ve müşterilerden tahsilat yapılır). Kutu, etkin modun gizli anahtarı eksikse ya da yanlış ön eke sahipse uyarır (bu durumda ödeme yöntemi ödeme sayfasında gizlenir) ve etkin modun webhook doğrulama jetonu boşsa uyarır (Xendit bildirimleri reddedilir, bu yüzden siparişler yalnızca müşteri mağazaya döndüğünde oluşturulur).

Xendit

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

Title: müşterilerin ödeme sayfasında gördüğü ödeme yöntemi adı. Siparişte kaydedilen ödeme yöntemi adı da budur. Varsayılan: Xendit. Zorunlu.

Description: ödeme sayfasında ödeme yönteminin altında gösterilen metin. Varsayılan: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

API anahtarları

Xendit Dashboard > Settings > Developers > API keys bölümünde, Money-in (faturalar) için yazma izni olan bir gizli API anahtarı oluşturun; bir kez test modunda, bir kez canlı modda. Faturanın nerede oluşturulacağını anahtar belirler. Kaydetme sırasında, alanının ön ekiyle başlamayan bir anahtar kaydedilmez ve sayfa örneğin Test secret key was not saved: it must start with xnd_development_ mesajını gösterir. Diğer ayarlar kaydedilir.

Test Mode: faturaları test gizli anahtarıyla oluşturur, bu yüzden gerçek para tahsil edilmez. Varsayılan: açık. Gerçek ödemeleri canlı gizli anahtarla kabul etmek için kapatın. Açık olduğu sürece müşteriler ödeme yönteminin altında Test mode: no real money is charged. mesajını görür.

Test Secret Key: Xendit test modunun gizli anahtarı. xnd_development_ ile başlar.

Live Secret Key: Xendit canlı modunun gizli anahtarı. xnd_production_ ile başlar.

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

Webhook'lar

Webhook, mağazanıza bir faturanın ödendiğini bildirir. Xendit Dashboard > Settings > Developers > Webhooks bölümünde, bu bölümdeki Webhook URL alanında gösterilen URL'yi hem test modunda hem canlı modda Invoices > Invoice paid için ayarlayın. İsteğe bağlı olarak Invoice expired için de ayarlayabilirsiniz. Okunabilir URL'ler etkinse şöyle görünür: https://your-shop/module/wcp_xendit_payment_gateway/webhook; başına /en/ gibi bir dil kodu da eklenmiş olabilir. Ayarların gösterdiği şekilde tam olarak kopyalayın.

Ardından her modun Webhook verification token değerini Xendit Dashboard'dan ilgili alana kopyalayın. Xendit bunu x-callback-token başlığında gönderir. Faturanın oluşturulduğu modun jetonu olmayan bildirimler reddedilir. Jeton yalnızca bildirimin Xendit'ten geldiğini kanıtlar: fatura durumu, tutarı ve para birimi her zaman o modun gizli anahtarıyla Xendit API'sinden yeniden okunur. Webhook olmadan sipariş, müşteri ödemeden sonra mağazaya döndüğünde oluşturulur.

Test Webhook Verification Token: Xendit test modunun webhook doğrulama jetonu.

Live Webhook Verification Token: Xendit canlı modunun webhook doğrulama jetonu.

Clear saved secrets: bir anahtarı veya jetonu işaretleyin ve kaldırmak için Save seçeneğine tıklayın. Boş bir alan kayıtlı değeri korur.

Ödeme

Invoice Description: Xendit faturasında gösterilen açıklama. {order_id}, {order_number} ve {site_name} yer tutucularını kullanabilirsiniz. Sipariş ödemeden sonra oluşturulduğu için {order_id} ve {order_number} sepet numarasıdır. HTML kaldırılır ve metin 255 karaktere kısaltılır. Varsayılan: Order #{order_id}.

Order Status After Payment: Xendit ödemeyi onayladıktan sonra ayarlanan sipariş durumu.

Gelişmiş

Debug Log: API isteklerini ve webhook'ları modül klasöründeki logs/xendit_p_debug.log.php dosyasına yazar. Dosya web üzerinden açılamaz. Hatalar ve uyarılar bu seçenek kapalı olsa bile her zaman kaydedilir. API anahtarları, jetonlar ve müşteri verileri kaydedilmez. Varsayılan: kapalı.

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

Delete Data on Uninstall: açıkken modülü kaldırmak modül ayarlarını ve günlüğü siler. Sipariş verileri (siparişlerin fatura kimlikleri) ve Xendit payment on hold sipariş durumu her zaman korunur. Varsayılan: kapalı.

Ödeme sayfası

Ödeme yöntemi, sepet para birimi IDR, PHP, VND, THB, MYR, USD veya SGD olduğunda gösterilir. Müşteri ödeme adımında bunu seçer (varsayılan olarak Xendit) ve onaylar. Modül, sepet toplamı için sepet para biriminde bir Xendit faturası oluşturur ve müşteriyi Xendit fatura sayfasına yönlendirir. IDR ve VND tutarları tam sayıya yuvarlanır, çünkü Xendit bu para birimleri için ondalık kabul etmez. Müşterinin e-posta adresi Xendit'e iletilir. Fatura sayfasında müşteri, Xendit hesabınızda bu para birimi için etkinleştirilmiş ödeme kanallarından biriyle (örneğin sanal hesap, e-cüzdan, QR kodu, perakende noktası veya kart) öder. Bu noktada henüz bir sipariş yoktur.

Ödemeden sonra müşteri mağazanıza döner. Sipariş, yalnızca Xendit onayladığında ödenmiş olarak işaretlenir: webhook ile ya da müşteri döndüğünde Xendit API'sine sunucu tarafında yapılan bir istekle. Sipariş ancak o zaman oluşturulur ve müşteri standart sipariş onay sayfasını görür. Xendit ödemeyi henüz onaylamadıysa, Payment confirmation sayfasında Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. mesajı ve Check again ile Back to checkout düğmeleri görünür. Webhook ulaştığı anda siparişi oluşturur.

Fatura başarısız olur ya da süresi dolarsa Xendit müşteriyi geri gönderir. Modül önce faturayı kontrol eder (başka bir sekmede ödenmiş olabilir), ardından artık ödenemeyecek şekilde süresini sona erdirir. Müşteri The Xendit payment was not completed. You can try again or choose another payment method. mesajıyla ödeme sayfasına döner. Sepet korunur.

Müşteri aynı sepeti yeniden ödeyebilir. Sepet toplamı, para birimi ve mod değişmemişse ve açık fatura en az beş dakika daha geçerliyse müşteri aynı faturaya yönlendirilir. Aksi halde eski fatura önce süresi sona erdirilir ve yeni bir fatura oluşturulur; böylece aynı sepet için hiçbir zaman iki açık fatura olmaz. Eski fatura zaten ödenmişse yeni bir ödeme yerine sipariş oluşturulur.

Xendit ödemeyi başlatamazsa müşteri ödeme sayfasında kısa bir mesajla kalır; örneğin Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., para biriminin hesabınız için kabul edilmediğini ya da sipariş toplamının Xendit tutar sınırlarının dışında olduğunu bildiren bir mesaj. Teknik neden günlüğe yazılır. Toplamı sıfır olan bir sepet Xendit ile ödenemez.

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

Ödeme her zaman Xendit sayfasında yapılır. Modülde yönetim panelinden iade, kayıtlı kart, abonelik veya düzenli ödeme, ödeme sayfasında kart veya e-cüzdan alanları, ayrı yetkilendirme ve tahsilat ya da xenPlatform alt hesapları yoktur.

Siparişler

Sipariş durumları

Henüz sipariş yok: müşteri Xendit'e yönlendirildi ve ödeme yapmadı ya da Xendit ödemeyi henüz onaylamadı. Yalnızca sepet vardır.

Payment accepted or Delivered: ödeme onaylandı. Durum, Order Status After Payment ayarını izler. Ödeme, Xendit fatura kimliğiyle işlem kimliği olarak kaydedilir; bir not fatura kimliğini, ödenen tutarı, ödeme kanalını ve modu gösterir.

Xendit payment on hold: ödenen fatura sepet toplamı veya para birimiyle eşleşmedi ya da toplamdan daha az ödeme yapıldı (örneğin fatura oluşturulduktan sonra sepet değiştirildi). Not durumu açıklar. Ödemeyi Xendit Dashboard'da kontrol edin, ardından siparişi tamamlayın ya da ödemeyi iade edin. Aynı sepetin başka bir faturası sonradan doğru tutarla ödenirse ödeme kaydedilir ve sipariş ödenmiş duruma geçer.

Zaten iptal edilmiş ya da iade edilmiş bir sipariş için bir fatura ödenirse sipariş durumu değişmez. Bir not, ödemeyi Xendit Dashboard'dan iade etmenizi ya da siparişi elle geri yüklemenizi ister. Zaten ödenmiş bir sipariş için ikinci bir fatura ödenirse sipariş değişmez ve bir not, mükerrer ödemeyi Xendit Dashboard'dan iade etmenizi ister.

Xendit payment bloğu

Sipariş sayfasında, fatura kimliği, mod (test ödemeleri için Test mode rozetiyle), ödeme durumu, siparişin tüm faturalarının listesi (tarih, fatura, dış kimlik, tutar ve ödenen tutar, durum, ödeme kanalı) ve siparişin Payment notes bölümünü içeren bir Xendit payment bloğu gösterilir.

İadeler

İadeler mağazadan Xendit'e gönderilmez. Ödemeyi Xendit Dashboard'da iade edin (Xendit payment bloğunda gösterilen fatura kimliğini arayın) ve iadeyi siparişe elle kaydedin. Sipariş sayfasındaki standart PrestaShop iade düğmeleri Xendit üzerinden para geri göndermez.

Lisans anahtarı

Modül, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox Xendit Payment Gateway, Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure sayfasında ayarların üstündeki ilk bloktur. 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 tarih ve alan adınız) ve Check now (durumu yeniden kontrol eder), Change key (başka bir anahtar girer) ve Remove key (anahtarı bu mağazadan kaldırır) düğmelerini gösterir. Bunların altında Product: presta-payment-xendit satırı ve Manage licenses and domains in your account bağlantısı bulunur; bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca modül için Configure izni 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 bir tarihle birlikte License expired on. Mağaza adresi değiştikten sonra ya da 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 tek 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 Xendit, ö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 yönetim paneline giriş yaptığınızı bilmez; bu yüzden ödeme yöntemi sizin için de gizlenir: modülü anahtar satın almadan önce ayarlayabilirsiniz, ancak ö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.

Bir lisans sona erdiğinde modül çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum, yönetim panelinde çalışırken otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün günde bir kez, ardından haftada bir kez. Cron job gerekmez. Modülü kaldırmak veya sıfırlamak lisans anahtarını ve lisans durumunu her zaman kaldırır.

Sorun giderme

Xendit ödeme sayfasında görünmüyor: lisansın etkin olduğunu, Enable/Disable seçeneğinin açık olduğunu, etkin modun doğru ön eke sahip bir gizli anahtarı olduğunu (test modunda xnd_development_ ile Test Secret Key, canlı modda xnd_production_ ile Live Secret Key) ve sepet para biriminin IDR, PHP, VND, THB, MYR, USD veya SGD olduğunu kontrol edin. Anahtar eksik ya da yanlışsa ayarlar sayfası uyarı gösterir. Payment > Preferences bölümünde modülün sepet para birimi, müşterinin ülkesi ve müşterinin grubu için izinli olduğunu kontrol edin.

Ödeme gerçekleşti ama sipariş oluşturulmadı: webhook çalışmıyor. Kullandığınız modun (test ya da canlı) Xendit Dashboard'unda Webhook URL alanında gösterilen URL'nin Invoice paid için ayarlandığını ve o modun doğrulama jetonunun ilgili alanda kayıtlı olduğunu kontrol edin. Xendit Dashboard, her webhook için mağazanızın yanıtını gösterir. Müşteri ödemeden sonra mağazaya döndüğünde de sipariş oluşturulur.

Webhook şu yanıtı veriyor: Webhook verification token is not configured: hiçbir doğrulama jetonu ayarlanmamış. Jetonu ayarlara yapıştırın.

Webhook şu yanıtı veriyor: Unauthorized: Xendit'in gönderdiği jeton, ayarlardaki hiçbir jetonla eşleşmiyor. Doğru modun jetonunu yeniden kopyalayın.

Webhook şu yanıtı veriyor: Token does not match the mode of this invoice: fatura diğer modda oluşturulmuş. Test bildirimi hiçbir zaman gerçek bir ödemeyi onaylamaz, tersi de geçerlidir. Webhook'u ve jetonu, sepetin ödendiği modda ayarlayın.

Webhook şu yanıtı veriyor: Ignored: not an invoice of this store: fatura bu mağaza tarafından oluşturulmamış, örneğin aynı Xendit hesabındaki başka bir entegrasyon tarafından. Xendit Dashboard'daki Test düğmesi de bu yanıtı alır; bu, URL'nin ve jetonun çalıştığını doğrular. Ignored: unknown order ve Ignored: unknown invoice, sepetin ya da faturanın bu mağazaca bilinmediği anlamına gelir.

Webhook şu yanıtı veriyor: Temporary error: faturayı kontrol etmek için Xendit API'sine ulaşılamadı, faturanın modunun gizli anahtarı eksik, sepet aynı anda başka bir istek tarafından güncelleniyordu ya da sipariş oluşturulamadı (örneğin modül devre dışı). Xendit webhook'u yeniden dener. Ödemeler iki modda da başlatıldıysa her iki gizli anahtarın da ayarlı olduğunu kontrol edin ve nedeni görmek için Debug Log seçeneğini açın.

Webhook URL'si tarayıcıda Method not allowed gösteriyor: bu normaldir. URL yalnızca Xendit'ten gelen istekleri kabul eder.

Bir anahtar kaydedilmiyor: değer, alanının ön ekiyle başlamıyor. Test anahtarları xnd_development_ ile, canlı anahtarlar xnd_production_ ile başlar.

Müşteri şunu görüyor: This payment method is temporarily unavailable: Xendit isteği reddetti; örneğin gizli anahtar yanlış ya da Money-in (faturalar) için yazma izni yok. Modül sayfasındaki Log alanına bakın. Fatura bilgileriyle ilgili bir mesaj, Xendit'in istek verilerini (örneğin e-posta) kabul etmediği anlamına gelir.

Müşteri şunu görüyor: A payment for this order was already received by Xendit and is being reviewed: bu sepetin daha önceki bir faturası ödenmiş, ancak sipariş henüz onaylanamamış. Ödemeyi Xendit Dashboard'da ve günlükte kontrol edin.

Müşteri şunu görüyor: We could not match this payment to an order: Xendit'ten gelen dönüş bağlantısı bu mağazadaki bir sepete ait değil ya da sepetin hiçbir faturası eşleştirilemedi. Ödemeyi Xendit Dashboard'da ve günlükte kontrol edin.

Ödemeden sonra sipariş Xendit payment on hold durumunda: Xendit payment bloğundaki notları okuyun. Ödenen tutar ya da para birimi sepetten farklıydı. Siparişi tamamlayın ya da ödemeyi Xendit Dashboard'da iade edin.

Geliştiriciler için modül, fatura isteğini, para birimlerinin listesini ve para birimi başına ondalık sayısını değiştirmek üzere actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies ve actionWcpXenditCurrencyDecimals hook'larını sağlar.

Kaldırma

Modules > Module Manager sayfasına gidin, VibeFox Xendit Payment Gateway yanındaki menüyü açın ve Uninstall seçin. Bu modülün lisans anahtarı ve lisans durumu her zaman kaldırılır. Delete Data on Uninstall açıksa modül ayarları ve günlük silinir. Kapalıysa tüm ayarlar sonraki yeniden kurulum için korunur. Siparişlerin Xendit fatura verileri ve Xendit payment on hold sipariş durumu her zaman korunur. Mevcut siparişler ödeme notlarını ve işlem kimliklerini korur.

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