İçeriğe geç
Better Payment
Referans

Sürüm notları

better-payment'in sürüm geçmişi ve geriye uyumsuz değişiklikleri.

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) ve halkbankmkd (Halkbank Makedonya, MKD ile) 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_BLOCKED ve RATE_LIMITED kodlarını $ERROR_CODES üzerinden verir. Sayaç anahtarları tuzlanmış hash'lerden türetilir ve giriş noktası better-payment/fraud adı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: localizedErrors artık i18n adını taşıyor ve Better Auth'un i18n plugin'i gibi çalışıyor: yerleşik locales ile translations, defaultLocale ve her handler yanıtı için detection stratejileri (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/nestjs ile 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' ile initThreeDSPayment() 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ı: captcha eklentisi, ö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 da sipay({ brand: 'qnbpay' }) ile. Teşekkürler @sizinajans.
  • Rate Limiting: Yeni rateLimit plugin'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 ve X-Forwarded-For yalnızca trustProxy etkinken 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ı: threeDSTimeout eklentisi 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 POST endpoint'leri acceptForm verilmedikçe form gövdelerini reddeder (CSRF), hata fırlatan bir onRequest hook'u 503 döner; hız sınırı store hata verdiğinde artık sessizce kapanmaz (eski davranış için passOnStoreError).
  • Veri maskeleme: fields ve custom varsayı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 getActor ile 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 UNKNOWN yerine belirli bir code döndürüyor (önce bankanın Banka_Sonuc_Kod alanı, sonra Param'ın Sonuc kodu). Tablo PARAMPOS_ERROR_CODES olarak dışa açılır.

0.11.0

Eklenenler

  • chaos plugin'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. allowProduction verilmedikçe production modunda ç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.
  • notifications plugin'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_key alanı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 Provision ile tamamlanır. Aynı gün iptal, tam ve kısmi iade ve durum sorgusu da desteklenir.

0.9.0

Eklenenler

  • Handler yanıtları exposeRawResponse: true verilmedikçe sağlayıcının rawResponse alanını içermez; idempotency.scope farklı çağıranların Idempotency-Key yanıtlarını birbirinden ayırır.

Düzeltilenler

  • buyer.email doğ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ı maxBodySize ile 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çin loader ve action dö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() ve getPayment() gibi ödemenin paymentId'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 kalemin paymentTransactionId'sini verin. paymentId alanına paymentTransactionId geçen kodun bu değeri yeni paymentTransactionId alanına taşıması gerekir.

Eklenenler

0.6.0

Eklenenler

  • Elysia adapter'ı: better-payment/elysia handler'ı 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

0.5.1

Eklenenler

Değişenler

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)

  • BetterPayment sınıfının yerini betterPayment({ providers, plugins }) aldı; sağlayıcılar iyzico(), paytr(), akbank() ve parampos() ile oluşturuluyor. enabled alanı kaldırıldı.
  • providers iç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/plugins altı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ı olan MockProvider. 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/fastify ve better-payment/hono handler'ı tek satırda bağlar; toFetchHandler Workers, Deno ve Bun'u kapsar.
  • Dokümantasyon artık Türkçe de okunabiliyor.

Değişenler

  • PROVIDER_DEFAULT_URLS, RemoteProviderType ile tiplenir (mock dışı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 fetch ve WebCrypto kullanır.
  • Özel bir fetch uygulaması (proxy, test stub'ları) için fetch seçeneği.
  • Özel sağlayıcılar için HttpClient ve HttpError dış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ılar setupAxiosLogging() / setupAxiosRetry() yerine createHttpClient() 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) ve voidAuthorization() serbest bırakır. iyzico, Parampos ve Akbank; PayTR henüz desteklenmiyor.
  • Kayıtlı kartlar: ödeme sırasında saveCard ile kartı kaydedin, sonra storedCard: { customerToken, cardToken } ile ödeme alın ve kartları saveCard(), listCards() ve deleteCard() 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 authorize hook'u gerektirir.

Değişenler

  • PaymentRequest.paymentCard tiplerde opsiyonel; çalışma anında paymentCard ya da storedCard'dan biri zorunludur.
  • Bir sağlayıcı bir işlemi desteklemediğinde handler 500 yerine 400 dö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 code taşır (INSUFFICIENT_FUNDS, CARD_DECLINED, THREEDS_FAILED, INVALID_HASH, ...). errorCode sağ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: false ile kapatılabilir.
  • Parampos taksitleri: installmentInfo(), calculatePaidPrice() ve getInstallmentRates() Param oranlarınızı kullanır.
  • Tekrar eden callback'ler bir kez işlenir; veri değiştiren handler route'ları Idempotency-Key başlığını kabul eder. IdempotencyStore varsayılan olarak bellek içidir; birden çok örnekle Redis ya da bir veritabanı kullanın.
  • PaymentErrorCode ve PaymentStatus, better-payment/client'tan dışa açılır.

Değişenler

  • İstek doğrulama hataları errorCode: 'VALIDATION_ERROR' döner; önceden errorCode boştu.
  • any içermeyen daha sıkı public tipler: rawResponse ve handler gövdeleri unknown; onCallback / callbackRedirect bir PaymentResponse alır.
  • NETWORK_ERROR mesajları 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_Pay ile 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 authorize hook'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_key ile, imzalanan veriye merchant_salt eklenerek imzalanır. user_basket, TL fiyatlı base64 JSON'dur. merchant_oid alfanümerik olmalıdır. test_mode sandbox moduna göre ayarlanır. İade tutarları TL cinsindendir. Durum sorguları /odeme/durum-sorgu kullanır. Bildirimler düz OK ile 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 iptaller TP_Islem_Iptal_Iade_Kismi2, durum sorguları TP_Islem_Sorgulama4, BIN sorguları BIN_SanalPos kullanı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 tamamlama mdStatus=1 şartı arar. retrieveSubscription GET kullanır.

Geriye uyumsuz değişiklikler (3.x'e göre)

AlanÖnceŞimdi
PayTR configapiKey, secretKey, merchantId, merchantSaltmerchantId, merchantKey, merchantSalt, testMode?
Akbank configmerchantId, terminalId, storeKey, …merchantSafeId, terminalSafeId, secretKey
Parampos configayrıca apiKey/secretKey isteniyorduclientCode, clientUsername, clientPassword, guid
paymentId (PayTR/Akbank/Parampos)sağlayıcı token'ı / işlem GUID'isizin sipariş numaranız
Zaman aşımlarıfailurepending + errorCode: 'NETWORK_ERROR'
Handlertüm route'lar herkese açık, her zaman HTTP 200açıkça etkinleştirilen route'lar, authorize, başarısızlıkta 422
Desteklenmeyen para birimisessizce TRYhata