Sunucu SDK'ları

Paymos, sekiz dil ekosistemi için resmî sunucu taraflı SDK'lar geliştirir. Her SDK; aynı faturalar, çekimler, ödeme kanalları, kanal yatırmaları, bakiyeler, sunucu saati, imleç sayfalaması, hata, yeniden deneme, istek imzalama ve webhook doğrulama sözleşmesini kapsar.

Sekiz istemcinin tamamı kendi ekosisteminin paket deposunda yayımlanmıştır. Kurulumu oradan yapın; kaynak kodu okumak için depoyu kullanın.

Dil	Paket deposu	Kurulum	Resmî kaynak
JavaScript / TypeScript	npm	npm i @paymos/sdk	Paymos-labs/typescript-sdk
Python	PyPI	pip install paymos-sdk	Paymos-labs/python-sdk
PHP	Packagist	composer require paymos/php-sdk	Paymos-labs/php-sdk
Go	Go modules	go get github.com/Paymos-labs/go-sdk/v2	Paymos-labs/go-sdk
.NET	NuGet	dotnet add package Paymos	Paymos-labs/dotnet-sdk
Java	Maven Central	io.paymos:paymos-java	Paymos-labs/java-sdk
Ruby	RubyGems	gem install paymos	Paymos-labs/ruby-sdk
Rust	crates.io	cargo add paymos	Paymos-labs/rust-sdk

Java'da tek satırlık bir kurulum komutu yoktur: io.paymos:paymos-java bağımlılığını pom.xml dosyanıza veya Gradle yapılandırmanıza ekleyin.

Değişmez bir vMAJOR.MINOR.PATCH sürüm etiketi kullanın. Her deponun sürüm sayfası; desteklenen çalışma zamanını, değişiklik günlüğünü ve sürümün üretildiği kaynak commit'i içerir.

Ortak API yüzeyi

Tüm istemciler altı kaynak sunar:

• —system — istek saati hizalaması için sunucu saatini getirir
• —invoices — oluşturma, getirme, listeleme, iptal, ödeme onayı ve sandbox simülasyonu
• —withdrawals — oluşturma, getirme, listeleme, iptal ve sandbox tamamlama simülasyonu
• —paymentChannels — oluşturma, getirme, listeleme, bloklama, blok kaldırma ve sandbox yatırma simülasyonu
• —paymentChannelDeposits — tek yatırmayı getirir, onaylanmış yatırma akışını okur
• —balances — para birimine göre gruplanmış kullanılabilir bakiyeleri listeler

İki kanal kaynağını her istemci kendi dilinin yazım geleneğine göre adlandırır: TypeScript, PHP ve Java'da paymentChannels; Python, Ruby ve Rust'ta payment_channels; Go ve .NET'te PaymentChannels.

Liste yardımcıları, azami sayfa sınırı olan imleç sayfalaması kullanır ve iki kez dönen bir imleci reddeder. Otomatik yeniden denemeler Retry-After değerine uyar; durum değiştiren istekler aktarım hatalarında veya genel sunucu hatalarında yeniden denenmez. Hız limitine takılan bir istek yeniden denenebilir; çünkü API onu işleme almamıştır.

Sekiz dil, tek sözleşme

Ortak olan yalnızca uç nokta listesi değil, davranışın kendisi. Dilden bağımsız tek bir uygunluk paketi; istek imzasına hangi baytların girdiğini, yukarıdaki yeniden deneme kurallarını, imleç yineleyicilerinin işleyişini ve webhook doğrulamasını sabitler. Bir sürüm, ancak SDK'nın kendi testleri bu pakete karşı koştuktan sonra çıkar.

Pratikte şu anlama gelir: entegrasyonu bu dillerden birinden diğerine taşıdığınızda imza, sayfa gezinme, yeniden deneme ve webhook davranışı olduğu gibi kalır. Aynı filtreli liste isteğini iki SDK aynı baytlarla imzalar.

PHP'ye özel olan katman

PHP SDK'sında, başka hiçbir istemcide bulunmayan bir CMS entegrasyon katmanı var: webhook'u API'den taze bir okumayla karşılaştıran ters doğrulama, sipariş serbest bırakılmadan önce tutar ve para birimi denetimi, takılabilir bir olay deposuyla yinelenen olayların ayıklanması, sandbox ve canlı secret'ı aynı anda tutan bir doğrulayıcı, mutabakat, olaydan sipariş eylemine eşleme ve şifreli kimlik bilgisi saklama.

CMS eklentilerinin bu kadar ince olmasının nedeni bu katman: sipariş durumlarının mantığı, sekiz kez üstte değil, altlarındaki SDK'da bir kez duruyor. Diğer yedisi için bunların hiçbiri geçerli değil; onlarda istemci, imza, kaynaklar, sayfalama ve webhook doğrulaması var, fazlası yok.

Güvenlik kuralları

İstek kimlik doğrulaması ve webhook kimlik doğrulaması farklı imzalar kullanır. API istekleri kanonik istek üzerinde base64 HMAC-SHA256 kullanır. Webhook'lar {timestamp}.{tam ham gövde} üzerinde hex HMAC-SHA256 kullanır. JSON'u çözmeden önce ayrıştırılmamış istek baytlarını SDK doğrulayıcısına verin. Doğrulayıcı, varsayılan olarak şu andan beş dakikadan fazla uzaklaşmış bir zaman damgasını reddeder ve iki v1 değeri taşıyan bir başlığı kabul eder; böylece secret rotasyonu size kod değişikliğine mal olmaz.

Uç nokta şemaları ve örnekler için şuradan devam edin: Kimlik Doğrulama, Faturalar, Çekimler, Bakiyeler ve Webhook'lar.