İçeriğe geç
Better Payment
Kavramlar

Plugin'ler

Better Payment'e plugin'lerle özellik ekleyin — ödeme olayları, sağlayıcı yönlendirme ve kendi mantığınız.

0.5.0 sürümünde eklendi

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çaNe yaparÖrnek
eventsÖdeme olaylarını dinlerSipariş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ştirebilirHata mesajlarını çevirmek
initİlk işlemden önce bir kez çalışırKomisyon tablolarını yüklemek, önbelleği ısıtmak
methodsÖdeme nesnesine üye eklerpayment.router.quote()
endpointsHTTP handler'a adres eklerPOST /api/pay/router/quote
$ERROR_CODESPlugin'in hata kodlarını tanımlarNO_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:

PluginNe yapar
i18nMüşteriler için, kendi dillerinde hata mesajları (İngilizce, Türkçe, Almanca, Rusça ve Arapça dahil)
chaosUygulamanızın hataları nasıl karşıladığını test etmek için işlemlere hata ve gecikme enjekte eder
notificationsSatışları, iadeleri ve hataları Slack, Discord, Telegram veya kendi kanalınıza gönderir
openAPIHandler endpoint'leri için OpenAPI 3.1.0 şema üretimi ve etkileşimli Scalar API referansı
failoverBir sağlayıcı çöktüğünde ödemeyi devre kesici (circuit breaker) ile yedek sağlayıcılarda yeniden dener
currencyConversionTutarları TCMB kurlarıyla dönüştürür; kâr marjı, kuruş hassasiyetinde sepet ve iadede kur kilidi
redactKart verilerini, CVV'yi ve kişisel verileri loglarda, olaylarda ve denetim kayıtlarında maskeler
threeDSTimeoutBaş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
rateLimitBot saldırılarına ve kart deneme girişimlerine karşı HTTP handler isteklerini sınırlandırır
pendingResolverZaman aşımına uğrayan ödemeleri (NETWORK_ERROR) belirli takvimle sorgular ve çözer
refundApprovalBelirli 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
mcpBetter Payment'ı yapay zekâ ajanları için Model Context Protocol (MCP) sunucusu olarak sunar
telemetryHer sağlayıcı çağrısı için OpenTelemetry uyumlu span ve metrikler; niteliklerde kart verisi yok
fraudRulesIP, 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)
commissionRouterHer ödemeyi kendi komisyon oranı tablolarınıza göre en ucuz uygun sağlayıcıya yönlendirir (alt yol better-payment/commission-router)
routingHer ö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.