Modül ne yapar
- Faturada iki düğme: Pay by card / PayPal (%4,5) ve coin seçicili Pay with crypto (%1,5). İkisinden biri kapatılabilir.
- Müşteri fatura bakiyesini öder, bu yüzden kısmen ödenmiş faturalar da çalışır.
- Ödeme, modül onu API üzerinden yeniden okuduktan sonra
addInvoicePaymentile işlenir: ödenmiş, aynı tutar ve para birimi. UTOPAY ödeme kimliği işlem kimliği olur; böylece bir ödeme asla iki kez işlenmez. - UTOPAY’in kabul etmediği para birimindeki faturalar (örneğin RUB) Convert To For Processing para biriminde ödenir; fatura kendi para biriminde alacaklandırılır.
- Fatura görüntülenirken hiçbir çağrı yapılmaz: ödeme yalnızca müşteri bir düğmeye bastığında oluşturulur.
Kurulum
- Yukarıdaki ZIP’i indirip açın.
utopay-whmcsklasörünün içeriğini WHMCS kök dizinine yükleyin;modulesklasörü sizinkiyle birleşir:modules/gateways/utopay.php,modules/gateways/utopay/,modules/gateways/callback/utopay.php.- UTOPAY panelinde Integration → API keys bölümünü açın ve test anahtarı
utopay_sk_test_…oluşturun. - WHMCS yönetimi → System Settings → Payment Gateways → All Payment Gateways → UTOPAY.
- Anahtarı yapıştırın, ödeme seçeneklerini belirleyin ve kaydedin.
- Kripto için: EVM cüzdanınızı panelde ekleyin (Project settings → Funds & payouts, Crypto wallets bölümü) ve coinleri modül ayarlarında listeleyin.
Ayarlar
| Alan | Ne yapar |
|---|---|
| Secret key | Sandbox için utopay_sk_test_…, gerçek ödemeler için utopay_sk_live_…. |
| Payment options | Kart / PayPal ve kripto, yalnızca kart ya da yalnızca kripto. |
| Crypto coins | Virgülle ayrılmış tickerlar, örneğin bep20/usdt,erc20/usdt,polygon/usdc. Tam liste: https://api.utopay.app/v1/crypto/coins. |
| Card method | Boş: müşteri seçer. Ya da herkesi doğrudan tek bir yönteme yönlendirin (Stripe, PayPal, Revolut…). |
| Convert To For Processing | Standart WHMCS seçeneği: fatura para birimi desteklenmediğinde ödemenin yapılacağı para birimi. |
Test ödemesi
- Test anahtarıyla müşteri alanında ödenmemiş bir faturayı açın ve Pay by card / PayPal düğmesine basın.
- UTOPAY sandbox’ı açılır. Ödemeyi simüle etmek için yeşil ✅ düğmesine basın.
- Faturaya dönersiniz. Birkaç saniye içinde Paid olur; Billing → Gateway Log ödeme kimliğiyle «Success» gösterir.
- Anahtarı
utopay_sk_live_…ile değiştirin.
Faturalar nasıl onaylanır
Her ödeme kendi bildirim URL’sini taşır: fatura numarası ve tutarlarla /modules/gateways/callback/utopay.php, gizli anahtarınızdan türetilen bir anahtarla imzalanır. UTOPAY her olayı imzalar (HMAC-SHA256) ve WHMCS 2xx dönmezse altı saat boyunca yeniden dener.
Modül iki imzayı da kontrol eder, ödemeyi API üzerinden yeniden okur ve yalnızca istenen tutar ve para birimiyle tam ödenmişse işler. Her adım Gateway Log’a yazılır.
Sorun giderme
- «Invalid request token»: fatura sayfası anahtar değişmeden önce açılmıştı; faturayı yenileyin.
- «amount is below the minimum»: bakiye, yöntemin ya da coinin minimumunun altında; müşteri başka birini seçebilir.
- Fatura Unpaid kalıyor: WHMCS internetten erişilebilir olmalı ve
/modules/gateways/callback/güvenlik duvarı ya da HTTP kimlik doğrulaması ile engellenmemeli. Billing → Gateway Log’a bakın. - Gateway Log: «Underpaid»: müşteri gerekenden az kripto gönderdi. Para cüzdanınızda: kısmi ödemeyi elle ekleyin.
- «currency … is not supported»: Convert To For Processing değerini USD ya da EUR yapın.
Sürüm geçmişi
- 1.0.1 — ortak UTOPAY çekirdeği güncellendi, davranış değişmedi.
- 1.0.0 — ilk sürüm: kart ve PayPal, kripto, Convert To For Processing, Rusça düğmeler.
SHA-256: ab17e573fe3784fb5217c408d389a51af7196173d29f79d287938f9320a4327a
Güncellendi · UTOPAY entegrasyon ekibi