Sürüm notları
better-payment'in sürüm geçmişi ve geriye uyumsuz değişiklikleri.
Sürüm geçmişi sıfırlandı. 0.0.1, yeniden yazılan paketin ilk sürümüdür. 1.x–3.x sürümlerinde hatalı sağlayıcı entegrasyonları ve atlatılabilen callback kontrolleri vardı; bunları kullanmayın. Gerekçe ve adım adım geçiş rehberi için 0.0.1'deki yenilikler sayfasına bakın.
0.12.0
Eklenenler
- Albaraka Türk sağlayıcısı: Albaraka'nın Posnet JSON API'si üzerinden 3D'siz satış, 3D Secure, iade, iptal, sipariş sorgusu ve ön provizyon. conversationId verilmediğinde bankaya uygun sipariş kimlikleri üretilir. Teşekkürler @sizinajans.
- Komisyon yönlendirici: her ödemeyi kendi oran tablolarınıza göre en ucuz uygun sağlayıcıya yönlendirir; açıklanabilir teklif, eşitlik ve pay üst sınırı politikaları, sipariş bazlı geçersiz kılma ve yalnızca ücret alınmadığında yedek sağlayıcı sunar. Teşekkürler @Enard52.
- Para birimi çevirme: Merkez Bankası (TCMB) kurları ile ödeme öncesi tutarları çevirin; kuruş hassasiyetinde sepet dağıtımı ve iade kur koruması sağlar. Teşekkürler @Enard52.
- Denizbank sağlayıcısı: InterVPos üzerinden 3D'siz satış, 3D Secure (3D Model), iade ve iptal. Callback hash'i
HASHPARAMSüzerinden yeniden oluşturulur, sonucu bankanın tahsilatı belirler. Teşekkürler @sizinajans. - EST Girogate: EST ödeme sayfası üzerinden iDEAL, Sofort, giropay, EPS, Bancontact, Przelewy24, Trustly ve diğer alternatif yöntemlerle ödeme; kart yerine
girogate: { method, country }gönderilir. Teşekkürler @sizinajans. - Yeni EST bankaları: EST sağlayıcısına
akbankest(Akbank'ın eski sanal POS'u) vehalkbankmkd(Halkbank Makedonya,MKDile) eklendi. Teşekkürler @sizinajans. - Sağlayıcı yedekleme (failover): sağlayıcı kesintilerinde veya geçici hatalarda ödemeleri devre kesici (circuit breaker) korumasıyla otomatik olarak yedek sağlayıcılara aktarın. Teşekkürler @Enard52.
- Fraud kuralları:
fraudRules()ödeme denemelerini IP, kart, BIN, e-posta veya alıcı bazında sayar; kart testi saldırılarını, engellenmiş BIN aralıklarını ve limitinizin üstündeki tutarları sağlayıcı çağrılmadan reddeder;FRAUD_BLOCKEDveRATE_LIMITEDkodlarını$ERROR_CODESüzerinden verir. Sayaç anahtarları tuzlanmış hash'lerden türetilir ve giriş noktasıbetter-payment/fraudadındadır. Teşekkürler @Enard52. - Garanti BBVA sağlayıcısı: GVP XML API üzerinden 3D'siz ve 3D Secure ödeme (3D, 3D_PAY), GarantiPay, iade, iptal ve sipariş sorgusu. 3D callback'leri
hashparamsüzerinden doğrulanır ve bankayla teyit edilir. Teşekkürler @sizinajans. - i18n plugin'i:
localizedErrorsartıki18nadını taşıyor ve Better Auth'un i18n plugin'i gibi çalışıyor: yerleşiklocalesiletranslations,defaultLocaleve her handler yanıtı içindetectionstratejileri (header,cookie,callback). Eski ad çalışmaya devam ediyor ve kullanımdan kaldırıldı. - MCP sunucusu eklentisi: Better Payment'ı yapay zekâ asistanları için Model Context Protocol (MCP) sunucusu olarak sunun. Teşekkürler @Enard52.
- NestJS adapter: ödeme handler'ını
better-payment/nestjsile bir NestJS controller'ına, Express veya Fastify platformunda ve@nestjs/*bağımlılığı olmadan bağlayın. Teşekkürler @Enard52. - Örnek mağaza: sepet, sunucu tarafı tutarlar, 3D Secure, ödeme olayları ve iadeler içeren çalıştırılabilir bir Next.js + Prisma mağazası. Teşekkürler @Enard52.
- OpenAPI ve Scalar Referans plugin'i: Ödeme handler endpoint'leri için OpenAPI 3.1.0 şeması üretir ve etkileşimli Scalar API dokümantasyon sayfası sunar. Teşekkürler @Enard52.
- PayTR Direct API ile 3D Secure:
threeDSMode: 'direct'ileinitThreeDSPayment()kartı kendi ödeme formunuzdan alır ve PayTR iFrame'i yerine imzalı bir Direct API formu döndürür. Teşekkürler @sizinajans. - Bekleyen Ödeme Çözümleyici: Zaman aşımına uğrayan ödemeleri salt okunur durum sorgularıyla kurtarır; eşzamanlı çözümleyiciler çalışsa bile her ödeme için yalnızca tek bir nihai olay yayınlanır. Teşekkürler @Enard52.
- Captcha doğrulaması:
captchaeklentisi, ödeme çalıştırılmadan önce Cloudflare Turnstile, Google reCAPTCHA v3 veya hCaptcha jetonlarını sunucu tarafında doğrular; kart test eden botlar sağlayıcıya ulaşamadan durdurulur. Callback'ler ve 3DS tamamlama adımları asla engellenmez. Teşekkürler @Enard52. - QNB sağlayıcısı: PayFor XML API üzerinden 3D'siz satış, 3D Secure (3D Model ve 3D Pay), iade, iptal ve sipariş sorgusu. 3D callback'leri ResponseHash ile doğrulanır ve bankayla teyit edilir. Teşekkürler @sizinajans.
- QNBpay: Sipay sağlayıcısı üzerinden QNBpay;
qnbpay()ya dasipay({ brand: 'qnbpay' })ile. Teşekkürler @sizinajans. - Rate Limiting: Yeni
rateLimitplugin'i handler uç noktalarını rota bazında sınırlandırır; kimlik varsayılan olarak uygulamanın kontrol ettiği bir kaynaktan gelir veX-Forwarded-ForyalnızcatrustProxyetkinken okunur. Teşekkürler @Enard52. - Veri maskeleme (PCI DSS & KVKK): sağlayıcı isteklerine dokunmadan kart hamili verilerini, CVV'yi ve kişisel verileri loglarda ve olaylarda maskeleyin. Teşekkürler @Enard52.
- İade onay plugin'i: Belirlenen limitin üzerindeki iade ve iptal işlemlerini yönetici onayına bağlayarak hatalı veya yetkisiz büyük para çıkışlarını önler. Teşekkürler @Enard52.
- Yönlendirme: her ödemeyi kendi kurallarınıza göre (kart ailesi, kartın menşei, tutar, taksit, sağlık) doğru sağlayıcıya gönderir; kuru çalışan
explain(), belirleyici 70/30 dağıtımı, denetim dinleyicileri ve her zaman ödemeyi alan sağlayıcıya giden iadeler sunar. Teşekkürler @Enard52. - Telemetri: Her sağlayıcı çağrısı için OpenTelemetry uyumlu span ve metrikler; niteliklerde kart verisi yok, bağımlılık yok. Teşekkürler @Enard52.
- 3D Secure zaman aşımı:
threeDSTimeouteklentisi başlatılan 3D Secure akışlarını izler ve müşterinin yarım bıraktıklarını ayarlanabilir süre sonunda düşürür. Her akış önce sağlayıcıdan yeniden sorgulanır, böylece geç gelen başarılı bir bildiri asla yok sayılmaz;payment.threeDS.expireStale()metodunu cron görevi veya sunucusuz zamanlı görev içinde çalıştırabilirsiniz. Teşekkürler @Enard52. - VakıfBank sağlayıcısı: 3D'siz satış, 3D Secure (MPI kaydı ve ardından kartı ve tutarı VakıfBank'ın kendi 3D kaydından alan VPOS provizyonu), iade ve iptal.
getPayment()desteklenmez. Teşekkürler @sizinajans. - Webhook forwarding plugin'i: Ödeme olaylarını diğer mikroservislere HMAC-SHA256 imzalı, üstel geri çekilmeli ve kart verilerinden arındırılmış webhook'lar olarak iletir. Teşekkürler @Enard52.
- Yapı Kredi sağlayıcısı: 3D'siz satış, Posnet OOS ile 3D Secure, iade, iptal ve sipariş durumu sorgusu. 3D ödemeler kendi kayıtlarınızdaki siparişle tamamlanır ve bankayla doğrulanır. conversationId verilmediğinde bankaya uygun sipariş kimlikleri üretilir. Teşekkürler @sizinajans.
Düzeltilenler
- Failover: kart çekildikten sonra da gelebilen HTTP 500, 502 ve 504 cevaplarından sonra yedek sağlayıcıya geçilmez, böylece bir gateway hatası müşteriyi iki kez ödetemez.
- PayTR sepet biçimi: Direct API ödemeleri artık sepeti Base64 yerine JSON olarak gönderir. iFrame sepet kodlaması ve token imzaları değişmez. Teşekkürler @sizinajans.
- Plugin yazma: plugin
POSTendpoint'leriacceptFormverilmedikçe form gövdelerini reddeder (CSRF), hata fırlatan bironRequesthook'u 503 döner; hız sınırı store hata verdiğinde artık sessizce kapanmaz (eski davranış içinpassOnStoreError). - Veri maskeleme:
fieldsvecustomvarsayılanların yerine geçmek yerine onlara eklenir, kart hamili adı ve sağlayıcı sırları varsayılan olarak maskelenir, kimlikler ve 3D Secure sayfası maskelenmeden döner. - İade onayı: HTTP uç noktalarında onaylayan, istek gövdesinden değil
getActorile oturumunuzdan alınır; iptaller ve okunamayan tutarlar onaya düşer, iki kez onaylanan talep bir kez iade edilir.
0.11.1
Düzeltilenler
- Parampos hata kodları: başarısız Parampos ödemeleri artık
UNKNOWNyerine belirli bircodedöndürüyor (önce bankanınBanka_Sonuc_Kodalanı, sonra Param'ınSonuckodu). TabloPARAMPOS_ERROR_CODESolarak dışa açılır.
0.11.0
Eklenenler
chaosplugin'i: uygulamanızın ret, kaybolan yanıt (NETWORK_ERROR) ve gecikmeleri nasıl karşıladığını test etmek için işlemlere bunları enjekte eder.allowProductionverilmedikçeproductionmodunda çalışmaz.- EST sağlayıcısı: İş Bankası, Ziraat Bankası, Halkbank, TEB ve Şekerbank tek bir sağlayıcıyla. 3D'siz ve 3D Secure ödeme (3D, 3D Pay, 3D Host, hash ver3), iade, iptal ve sipariş durumu sorgusu desteklenir. 3D callback'leri bankayla doğrulanır.
notificationsplugin'i: satışları, iadeleri ve başarısız ödemeleri arka planda ve kart verisi olmadan Slack, Discord, Telegram veya kendi kanalınıza gönderir. Başarısız olan bir kanal ödemeyi asla etkilemez.- Sipay sağlayıcısı: 3D'siz ve 3D Secure ödeme, Sipay'in şifreli
hash_keyalanıyla doğrulanan 3D callback'leri, tam ve kısmi iade, iptal, durum sorgusu, ön provizyon ve BIN/taksit sorgusu. Sipay test ortamında uçtan uca doğrulandı.
0.10.0
Eklenenler
- Kuveyt Türk sağlayıcısı: KT Pay Gate üzerinden 3D Secure ödeme; sipariş bankada kontrol edildikten sonra
Provisionile tamamlanır. Aynı gün iptal, tam ve kısmi iade ve durum sorgusu da desteklenir.
0.9.0
Eklenenler
- Handler yanıtları
exposeRawResponse: trueverilmedikçe sağlayıcınınrawResponsealanını içermez;idempotency.scopefarklı çağıranların Idempotency-Key yanıtlarını birbirinden ayırır.
Düzeltilenler
buyer.emaildoğrulaması boş alan adı bölümlerini reddeder ve artık geri izleme yapan bir düzenli ifade kullanmaz.
0.8.1
Düzeltilenler
- Framework adapter'ları 1 MiB'tan büyük istek gövdelerini belleğe okumak yerine 413 ile yanıtlar; sınırı
maxBodySizeile değiştirebilirsiniz. - Akbank: 3D Secure callback'leri sipariş geçmişi sorgusuyla doğrulanır; Akbank'taki sipariş kaydıyla eşleşmeyen callback reddedilir.
- HTTP handler form gövdesini yalnızca sağlayıcı callback'lerinde kabul eder; diğer aksiyonlar 415 döner, böylece başka bir sitedeki form bunları kullanıcının cookie'leriyle çağıramaz.
- Logger'a verilen hatalar artık sağlayıcı isteğinin gövdesini ve başlıklarını (kart verisi, kimlik bilgileri) içermiyor.
- iyzico: başarısız bir 3D Secure sonucu artık callback isteğinden alınan paymentId veya conversationId taşımıyor.
0.8.0
React Router adaptörü.
Eklenenler
- React Router adaptörü:
better-payment/react-router, bir splat resource route içinloaderveactiondöndürür; React Router v7 ve Remix v2 ile çalışır.
0.7.0
Sepet yardımcısı, Arapça hata mesajları ve iyzico'da paymentId ile iade. iyzico için geriye uyumsuz: aşağıdaki iade maddesine bakın.
Değişenler (geriye uyumsuz)
- iyzico iadeleri:
refund(),cancel()vegetPayment()gibi ödemeninpaymentId'sini alır ve ödemenin tamamından bir tutarı iade eder (/v2/payment/refund). Tek bir sepet kalemini iade etmek için ayrıca o kaleminpaymentTransactionId'sini verin.paymentIdalanınapaymentTransactionIdgeçen kodun bu değeri yenipaymentTransactionIdalanına taşıması gerekir.
Eklenenler
buildBasket(): indirimleri ve kargoyu sepet kalemlerine dağıtır; kalemlerin toplamı ödeme tutarını kuruşu kuruşuna tutar.- Hata mesajları için dil desteği: Arapça (
ar). Handler'daAccept-Language: arArapça'yı seçer. Katkısı için @poyrazavsever'e teşekkürler.
0.6.0
Eklenenler
- Elysia adapter'ı:
better-payment/elysiahandler'ı Elysia'ya (Bun) tek satırda bağlar:app.all('/api/pay/*', toElysiaHandler(payment), { parse: 'none' }). Katkısı için @ScottHallchico'ya teşekkürler.
0.5.2
Eklenenler
- Hata mesajları için dil desteği: Rusça (
ru). Handler'daAccept-Language: ru-RURusça'yı seçer. Katkısı için @ius-sharma'ya teşekkürler.
0.5.1
Eklenenler
- Hata mesajları için dil desteği: Almanca (
de). Handler'daAccept-Language: de-DEAlmanca'yı seçer. Katkısı için @ius-sharma'ya teşekkürler.
Değişenler
- Repo czaydev/better-payment adresine taşındı.
0.5.0
Plugin'ler ve tipli ödeme olayları. Geriye uyumsuz: new BetterPayment() yerine betterPayment() geldi; sağlayıcılar fabrika fonksiyonlarıyla oluşturuluyor. Bkz. 0.5'e geçiş.
Değişenler (geriye uyumsuz)
BetterPaymentsınıfının yerinibetterPayment({ providers, plugins })aldı; sağlayıcılariyzico(),paytr(),akbank()veparampos()ile oluşturuluyor.enabledalanı kaldırıldı.providersiçindeki her anahtar bir sağlayıcı kimliğidir;payment.<id>sağlayıcıya göre tiplidir.getEnabledProviders()string[]döner.
Eklenenler
- Plugin'ler: sağlayıcı işlemleri için before/after hook'ları, tipli metotlar, handler endpoint'leri ve hata kodları. Kendi plugin'inizi birkaç satırda yazın.
- Ödeme olayları: her sağlayıcı ve akış için tek bir tipli dinleyici; yalnızca doğrulanmış sonuçlar için yayınlanır.
- Hata mesajları için dil desteği:
better-payment/pluginsaltındaki ilk resmi plugin. Müşteriye yönelik İngilizce ve Türkçe mesajlar. defineProvider()ile özel sağlayıcılar ve imzalama için WebCrypto yardımcıları.
0.4.0
Sandbox olmadan test ve tek satırlık framework entegrasyonu. Mevcut 0.3.0 kodu çalışmaya devam eder.
Eklenenler
better-payment/testing: uygulama testleri için kimlik bilgisi ve ağ erişimi gerektirmeyen, bellek içi bir sağlayıcı olanMockProvider. Sihirli kart numaraları retleri, 3D Secure hatalarını, kaybolan yanıtları ve başarısız iadeleri kapsar; 3D Secure callback'leri gerçek handler'dan geçer.- Framework adapter'ları:
better-payment/next,better-payment/express,better-payment/fastifyvebetter-payment/honohandler'ı tek satırda bağlar;toFetchHandlerWorkers, Deno ve Bun'u kapsar. - Dokümantasyon artık Türkçe de okunabiliyor.
Değişenler
PROVIDER_DEFAULT_URLS,RemoteProviderTypeile tiplenir (mockdışındaki tüm sağlayıcılar).
0.3.0
Edge ortamları ve sıfır runtime bağımlılığı. Uygulama kodu değişmeden çalışmaya devam eder.
Eklenenler
- Edge ortamı desteği: aynı paket Node.js 20+, Vercel Edge, Cloudflare Workers, Deno ve Bun'da çalışır. Yalnızca
fetchve WebCrypto kullanır. - Özel bir fetch uygulaması (proxy, test stub'ları) için
fetchseçeneği. - Özel sağlayıcılar için
HttpClientveHttpErrordışa açıldı.
Değişenler
- Runtime bağımlılığı yok: axios kaldırıldı. Zaman aşımları, loglama ve yeniden deneme kuralları değişmedi.
PaymentProvider'dan türeyen özel sağlayıcılarsetupAxiosLogging()/setupAxiosRetry()yerinecreateHttpClient()kullanır.
0.2.0
Ön provizyon ve kayıtlı kartlar. Mevcut 0.1.0 kodu çalışmaya devam eder. İki özellik de her gece gerçek iyzico sandbox'ına karşı test edilir.
Eklenenler
- Ön provizyon:
authorize()/initThreeDSAuthorize()tutarı bloke eder,capture()tahsil eder (kısmi capture desteklenir) vevoidAuthorization()serbest bırakır. iyzico, Parampos ve Akbank; PayTR henüz desteklenmiyor. - Kayıtlı kartlar: ödeme sırasında
saveCardile kartı kaydedin, sonrastoredCard: { customerToken, cardToken }ile ödeme alın ve kartlarısaveCard(),listCards()vedeleteCard()ile yönetin. iyzico ve PayTR; Parampos ve Akbank henüz desteklenmiyor. - İkisi için handler route'ları ve tarayıcı client metotları. Capture, void ve kart route'ları bir
authorizehook'u gerektirir.
Değişenler
PaymentRequest.paymentCardtiplerde opsiyonel; çalışma anındapaymentCardya dastoredCard'dan biri zorunludur.- Bir sağlayıcı bir işlemi desteklemediğinde handler
500yerine400döner.
0.1.0
Sıfırlamadan sonraki ilk özellik sürümü. Mevcut 0.0.1 kodu çalışmaya devam eder; davranış değişiklikleri "Değişenler" altında listelenir. iyzico entegrasyonu artık her gece gerçek iyzico sandbox'ına karşı test ediliyor.
Eklenenler
- Birleşik hata kodları: her başarısız sonuç bir
codetaşır (INSUFFICIENT_FUNDS,CARD_DECLINED,THREEDS_FAILED,INVALID_HASH, ...).errorCodesağlayıcının ham kodunu korur. - Sağlayıcı çağrılmadan önce istek doğrulama. Geçersiz istekler tüm geçersiz alanları listeleyerek
code: 'INVALID_REQUEST'döner.validate: falseile kapatılabilir. - Parampos taksitleri:
installmentInfo(),calculatePaidPrice()vegetInstallmentRates()Param oranlarınızı kullanır. - Tekrar eden callback'ler bir kez işlenir; veri değiştiren handler route'ları
Idempotency-Keybaşlığını kabul eder.IdempotencyStorevarsayılan olarak bellek içidir; birden çok örnekle Redis ya da bir veritabanı kullanın. PaymentErrorCodevePaymentStatus,better-payment/client'tan dışa açılır.
Değişenler
- İstek doğrulama hataları
errorCode: 'VALIDATION_ERROR'döner; öncedenerrorCodeboştu. anyiçermeyen daha sıkı public tipler:rawResponseve handler gövdeleriunknown;onCallback/callbackRedirectbirPaymentResponsealır.NETWORK_ERRORmesajları taşıma hatasının adını verir (ECONNRESET, zaman aşımı, ...).- Yayınlanan build küçültüldü: 29.6 kB yerine yaklaşık 19 kB gzip.
0.0.1
Güvenlik
- Parampos: 3D callback hash'i yalnızca yapılandırmanızdaki GUID ile doğrulanır. Önceki sürümler GUID'i callback içeriğinden okuyordu; bu da herkesin başarılı bir ödeme uydurmasına izin veriyordu.
- Parampos / Akbank: bir 3D callback tek başına artık başarılı ödeme sayılmıyor. Parampos
TP_WMD_Payile tamamlar; Akbank HMAC imzalı sonuçla 3D_PAY modelini kullanır. Eksik bir sonuç kodu artık başarı sayılmıyor. - HTTP handler: varsayılan olarak güvenli. Varsayılan olarak yalnızca callback'leri ve kart sorgularını açar. İade, iptal, ödeme sorgusu ve abonelik yönetimi bir
authorizehook'u gerektirir. - Yeniden denemeler yalnızca idempotent istekleri tekrar gönderir; böylece bir zaman aşımı artık çift çekime ya da çift iadeye yol açamaz.
- İmzalar sabit sürede karşılaştırılır.
Sağlayıcı düzeltmeleri
- PayTR: istekler
merchant_keyile, imzalanan veriyemerchant_salteklenerek imzalanır.user_basket, TL fiyatlı base64 JSON'dur.merchant_oidalfanümerik olmalıdır.test_modesandbox moduna göre ayarlanır. İade tutarları TL cinsindendir. Durum sorguları/odeme/durum-sorgukullanır. Bildirimler düzOKile yanıtlanır. Gizli anahtarlar artık istek gövdelerinde gönderilmiyor. - Parampos:
TP_WMD_UCD/TP_WMD_Pay, virgüllü ondalık tutarlar ve dokümante edilen hash kullanılır. İade ve iptallerTP_Islem_Iptal_Iade_Kismi2, durum sorgularıTP_Islem_Sorgulama4, BIN sorgularıBIN_SanalPoskullanır. Uydurma taksit oranları kaldırıldı. - Akbank: Akbank Sanal POS JSON API'sine göre yeniden yazıldı.
- iyzico: Checkout Form ve PWI sonuçları ödemenin kendi durumunu (
paymentStatus) bildirir. 3DS tamamlamamdStatus=1şartı arar.retrieveSubscriptionGET kullanır.
Geriye uyumsuz değişiklikler (3.x'e göre)
| Alan | Önce | Şimdi |
|---|---|---|
| PayTR config | apiKey, secretKey, merchantId, merchantSalt | merchantId, merchantKey, merchantSalt, testMode? |
| Akbank config | merchantId, terminalId, storeKey, … | merchantSafeId, terminalSafeId, secretKey |
| Parampos config | ayrıca apiKey/secretKey isteniyordu | clientCode, clientUsername, clientPassword, guid |
paymentId (PayTR/Akbank/Parampos) | sağlayıcı token'ı / işlem GUID'i | sizin sipariş numaranız |
| Zaman aşımları | failure | pending + errorCode: 'NETWORK_ERROR' |
| Handler | tüm route'lar herkese açık, her zaman HTTP 200 | açıkça etkinleştirilen route'lar, authorize, başarısızlıkta 422 |
| Desteklenmeyen para birimi | sessizce TRY | hata |