Plugin'ler
Better Payment'e plugin'lerle özellik ekleyin — ödeme olayları, sağlayıcı yönlendirme ve kendi mantığınız.
Plugin, kütüphaneyi değiştirmeden ödeme nesnesine davranış ekler. Ödeme olaylarına tepki verebilir, sağlayıcı işlemlerinden önce ve sonra kod çalıştırabilir, ödeme nesnesine metot ve HTTP handler'a adres ekleyebilir. Plugin'ler düz nesnelerdir; bu yüzden bir plugin çoğu zaman birkaç satıra sığar ve kendi plugin'inizi yazabilirsiniz.
Plugin kullanmak
import { betterPayment, iyzico, paytr } from 'better-payment';
import { auditLog } from './plugins/audit-log';
export const payment = betterPayment({
providers: {
iyzico: iyzico({ /* ... */ }),
paytr: paytr({ /* ... */ }),
},
plugins: [auditLog()],
});Plugin'ler plugins dizisindeki sırayla çalışır. Hook'ları, olay dinleyicileri ve endpoint'leri ödeme nesnesi oluşturulurken kaydedilir. init fonksiyonları ilk işlemden önce bir kez çalışır.
Bir plugin neler yapabilir?
| Parça | Ne yapar | Örnek |
|---|---|---|
events | Ödeme olaylarını dinler | Siparişleri güncellemek, e-posta göndermek, denetim kaydı tutmak |
hooks.before | İşlemden önce çalışır. Sağlayıcıyı seçebilir, isteği değiştirebilir ya da sağlayıcıyı çağırmadan bir sonuç döndürebilir | Ödemeleri en ucuz sağlayıcıya göndermek, bir kartı engellemek, sipariş numarası eklemek |
hooks.after | İşlemden sonra çalışır ve sonucu değiştirebilir | Hata mesajlarını çevirmek |
init | İlk işlemden önce bir kez çalışır | Komisyon tablolarını yüklemek, önbelleği ısıtmak |
methods | Ödeme nesnesine üye ekler | payment.router.quote() |
endpoints | HTTP handler'a adres ekler | POST /api/pay/router/quote |
$ERROR_CODES | Plugin'in hata kodlarını tanımlar | NO_ELIGIBLE_PROVIDER |
Plugin'in eklediği her şey tiplidir: payment.router.quote() otomatik tamamlanır, bir yazım hatası tip hatası olur.
İşlemler
Hook'lar şu işlemlerde çalışır; işlem ödeme nesnesinde (payment.createPayment()), bir sağlayıcıda (payment.iyzico.createPayment()) ya da HTTP handler üzerinden çağrılmış olabilir:
createPayment, initThreeDSPayment, completeThreeDSPayment, authorize, initThreeDSAuthorize, capture, voidAuthorization, refund, cancel, getPayment, saveCard, listCards, deleteCard, binCheck, installmentInfo
Sağlayıcıya özel metotlar (iyzico ödeme formu, PWI ve abonelikler, PayTR token ödemeleri) hook'suz çalışır.
Bir hook yalnızca ödeme nesnesinde yapılan çağrıları başka bir sağlayıcıya taşıyabilir. Bir sağlayıcıda (payment.iyzico.refund()) ya da handler'ın bir sağlayıcı adresi üzerinden yapılan çağrı her zaman o sağlayıcıda çalışır: iade, iptal ve durum sorguları ödemeyi alan sağlayıcıya gitmelidir.
Resmi plugin'ler
Resmi plugin'ler paketle birlikte gelir: çoğu better-payment/plugins altında, daha büyükleri kendi alt yolunda:
| Plugin | Ne yapar |
|---|---|
i18n | Müşteriler için, kendi dillerinde hata mesajları (İngilizce, Türkçe, Almanca, Rusça ve Arapça dahil) |
chaos | Uygulamanızın hataları nasıl karşıladığını test etmek için işlemlere hata ve gecikme enjekte eder |
notifications | Satışları, iadeleri ve hataları Slack, Discord, Telegram veya kendi kanalınıza gönderir |
openAPI | Handler endpoint'leri için OpenAPI 3.1.0 şema üretimi ve etkileşimli Scalar API referansı |
failover | Bir sağlayıcı çöktüğünde ödemeyi devre kesici (circuit breaker) ile yedek sağlayıcılarda yeniden dener |
currencyConversion | Tutarları TCMB kurlarıyla dönüştürür; kâr marjı, kuruş hassasiyetinde sepet ve iadede kur kilidi |
redact | Kart verilerini, CVV'yi ve kişisel verileri loglarda, olaylarda ve denetim kayıtlarında maskeler |
threeDSTimeout | Başlatılan 3D Secure ödemelerini takip eder, terk edilenleri zaman aşımına uğratır |
captcha | Ödeme işlemlerinden önce Turnstile, reCAPTCHA veya hCaptcha token'ını doğrular |
rateLimit | Bot saldırılarına ve kart deneme girişimlerine karşı HTTP handler isteklerini sınırlandırır |
pendingResolver | Zaman aşımına uğrayan ödemeleri (NETWORK_ERROR) belirli takvimle sorgular ve çözer |
refundApproval | Belirli bir limitin üzerindeki iade ve iptaller için yönetici onayı gerektirir |
webhookForwarding | Ödeme olaylarını diğer mikroservislere HMAC-SHA256 imzalı ve yeniden denemeli webhook olarak iletir |
mcp | Better Payment'ı yapay zekâ ajanları için Model Context Protocol (MCP) sunucusu olarak sunar |
telemetry | Her sağlayıcı çağrısı için OpenTelemetry uyumlu span ve metrikler; niteliklerde kart verisi yok |
fraudRules | IP, kart ve alıcı başına denemeleri sayar, kart testi saldırılarını sağlayıcı çağrılmadan reddeder (alt yol better-payment/fraud) |
commissionRouter | Her ödemeyi kendi komisyon oranı tablolarınıza göre en ucuz uygun sağlayıcıya yönlendirir (alt yol better-payment/commission-router) |
routing | Her ödemeyi kart ailesi, kartın menşei, tutar, taksit ve sağlığa göre doğru sağlayıcıya gönderir (alt yol better-payment/routing) |
Başka bir şeye mi ihtiyacınız var? Kendi plugin'inizi yazın; birkaç satır yeterli.