ZEN.COM

Gereken bilgiler

my.zen.com → mağazanızı seçin → Store settings → Terminal → ilgili terminali seçin. Üç değer gerekir:

• merchant_uuid: Terminal UUID
• secret_key: Paywall secret (checkout isteğinin imzası bununla hesaplanır)
• webhook_secret: IPN secret (ZEN'in gönderdiği bildirimin hash alanı bununla doğrulanır)

Panelinizde Ayarlar → Ödemeler → Yöntem ekle → ZEN.COM seçin, üç değeri girin.

Test ortamı: ZEN'in test hesabı ayrı bir ortamdır (secure.zen-test.com). Test terminalinizin değerlerini girip sandbox (test) modu kutusunu işaretleyin; canlıya geçerken canlı terminalin değerlerini girip kutuyu kaldırın.

Bildirim (IPN) adresi

Panel her ödeme isteğine kendi bildirim adresini customIpnUrl olarak ekler; ZEN o ödeme için bu adrese bildirim gönderir. Adres:

https://<panel-alan-adınız>/payments/zen/callback

Yine de aynı adresi my.zen.com'da Store settings → Terminal → IPN URL alanına yazmanızı öneririz: customIpnUrl boş kalırsa ZEN oradaki adresi kullanır. Terminalin IPN'i her zaman açık olmalıdır; bakiye yalnız bu bildirimle yüklenir.

Dönüş adresleri (urlSuccess / urlFailure) da her isteğe eklenir; ZEN panelinde ayrıca bir şey yapılmaz.

Akış

1. Müşteri tutarı girer, ZEN.COM'u seçer. Telefon zorunlu değildir.
2. Panel, imzalı bir isteği ZEN'e gönderir (terminalUuid, tutar, para birimi, ödeme numaramız merchantTransactionId, müşteri adı/e-postası, tek satırlık "Bakiye yükleme" kalemi). ZEN bir redirectUrl döner, müşteri ZEN'in ödeme sayfasına yönlendirilir; kart bilgisi ve 3D Secure orada.
3. Ödeme sonuçlanınca müşterinin tarayıcısı panele geri döner ("Bakiye yükle" sayfası). Bu dönüş bakiye yüklemez.
4. ZEN'in sunucusu bildirim adresine JSON bir IPN gönderir. Panel hash alanını IPN secret ile yeniden hesaplar (sha256(merchantTransactionId + currency + amount + status + IPN secret)); eşleşmeyen bildirim reddedilir.
5. Doğrulanan bildirimde durum ACCEPTED ise bakiye yüklenir. Panel bildirime {"status":"ok"} ile cevap verir; cevap alamayan ZEN aynı bildirimi bir gün boyunca yeniden gönderir.

Aynı işlem + aynı durum için gelen ikinci bildirim yok sayılır; bakiye iki kez yüklenmez. PENDING sonrası gelen ACCEPTED ayrı bir olay olarak işlenir.

Müşterinin adı ZEN'e kullanıcı adından üretilir ve imza hesabında büyük/küçük harf farkı sorun çıkarmasın diye Türkçe karakterler ASCII'ye çevrilir ("Şükrü" → "Sukru"). Adres alanları ZEN'de zorunlu olmadığı için gönderilmez.

Durumlar

ZEN durumu	Panelde
ACCEPTED	tamamlandı, bakiye yüklendi
REJECTED, CANCELED	başarısız
AUTHORIZED	beklemede (kart provizyonu alındı, tahsilat yapılmadı). ZEN ACCEPTED gönderince tamamlanır ya da Admin → Ödemeler'den tamamlayabilirsiniz
NEW, PENDING	beklemede, sonraki bildirim beklenir

TRT_PURCHASE dışındaki bildirimler (iade vb.) doğrulanır ve cevaplanır ama bakiye değiştirmez.

Para birimleri

ZEN'in doğrudan desteklediği para birimleri: EUR, GBP, PLN, USD, AED, AUD, CAD, CHF, CNY, CZK, DKK, HKD, HUF, ILS, JPY, KES, MXN, NOK, NZD, QAR, RON, SAR, SEK, SGD, THB, TRY, UGX, ZAR. Panelinizin para birimi bunlardan biri olmalı; başka bir birimde ödeme başlatılmaz. Tutar her zaman iki ondalıkla gönderilir. Terminalinizde hangi para birimlerinin ve ödeme yöntemlerinin açık olduğu ZEN sözleşmenize bağlıdır.

Sık sorunlar

• Ödeme sayfası açılmıyor, "ZEN: …" hatası: Paywall secret ya da Terminal UUID yanlış, ya da test/canlı karışmış. Hata mesajı ZEN'in döndürdüğü metindir.
• Aynı ödeme için ikinci deneme reddediliyor: ZEN aynı merchantTransactionId ile ikinci isteği kabul etmez. Yeni bir ödeme başlatın.
• Ödeme ZEN'de ACCEPTED ama bakiye yok: IPN secret yanlışsa bildirim "invalid signature" ile reddedilir; my.zen.com'daki IPN secret ile paneldeki webhook_secret aynı olmalı. Bildirim adresinin dışarıdan erişilebilir ve HTTPS olduğundan emin olun (DNS devri tamamlanmamış alan adına bildirim ulaşmaz).
• Ödeme "beklemede" kaldı: ZEN henüz son durumu göndermedi (bazı yerel yöntemlerde onay gecikir) ya da durum AUTHORIZED. Admin → Ödemeler'deki nota bakın.