Rust SDK

Güncel kaynak sürümü: 0.1.2. Aşağıdaki önceki 0.1.1 kayıt deposu sürümü doğrulanmış yayındır; yeni kaynak yamasının orada yayımlandığı iddia edilmez.

Yeni kaynak yaması mağaza sitesi için somut bir sunum örneği ekler. Varsayılan gömülü ödemedir: yalnız resmi Lunixi bundle yüklenir ve mevcut form mount edilir; yöntem ve çoklu kart seçenekleri Lunixi panelinde kalır. İsteğe bağlı yönlendirme yalnız backend paymentPageUrl adresini, tam HTTPS pay.lunixi.com/payment/ doğrulamasından sonra kullanır. Adresin token’ı gömülü token’dan farklı olabilir. Eksik adres gömülü ödemeyi engellemez; yönlendirme aynı deneme/anahtarla inceleme veya uzlaştırmada kalır. Tarayıcı token’ından adres üretmeyin. Formdan önce müşteri/sipariş sahipliğini ve yerel tarayıcı CSRF’yi doğrulayın; Cache-Control: private, no-store gönderin, mağazanın CSP nonce değerini koruyun; token, HTML ve yönlendirme adreslerini loglamayın. Genel yanıt verisi paymentPageUrl alanını korur; yeni tipli ürün eşitliği iddiası yoktur.

lunixi, Rust 1.89+ (edition 2024) sunucu uygulamaları için asenkron SDK'dır. Tokio, reqwest ve sertifika doğrulamalı Rustls kullanır. Axum ve Actix Web ile çalışır; servisler ortak imza/token/taşıma katmanını paylaşır.

crates.io üzerinden kurulum

Lunixi 0.1.1, crates.io’da son doğrulanan sürümdür (opens in a new tab). Bu eski registry seçeneği, güncel 0.1.2 kaynak/örnek güncellemesinden ayrıdır; burada crates.io 0.1.2’nin erişilebilir olduğu iddia edilmez. Önceki sürümü Cargo.toml dosyanızda sabitlemek için:

[dependencies]
lunixi = "=0.1.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Güncel checkout sunum örneği için eski registry bağımlılığı yerine yayımlanmış v0.1.2 kaynak etiketini kullanın:

[dependencies]
lunixi = { git = "https://github.com/Lunixi-Payment/lunixi-rust", tag = "v0.1.2" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

v0.1.2 kaynak kodu ve örnekleri (opens in a new tab). Çözümlenen kaynak commit’ini korumak için Cargo.lock dosyasını saklayın. Sunum yardımcıları etiketli kaynak örnektedir; kütüphane bağımlılığını eklemek bir mağaza uygulaması kurmaz veya sipariş yetkisi sağlamaz.

Kalıcı inbox için lunixi bağımlılığına features = ["sqlite"] ekleyin. Paketlenmiş SQLite C derleyicisi gerektirir; varsayılan SDK özelliklerinde SQLite derlenmez.

Merchant başına bir istemci

use lunixi::{Client, Config};
 
let mut config = Config::new(
    "https://api-gateway.lunixi.com",
    std::env::var("LUNIXI_KEY_ID")?,
    std::env::var("LUNIXI_PRIVATE_KEY_PEM")?,
);
config.max_retries = 2;
let client = Client::new(config)?;

Ed25519 açık anahtarını panelde kaydedin; özel anahtar sunucuda kalır. PKCS8 PEM, base64 PKCS8 DER, base64 32 bayt seed ve doğrulanmış base64 64 bayt keypair kabul edilir. TEST/LIVE ortamını merchant anahtarı seçer. Özel anahtar/secret tarayıcıya gönderilmez.

İstemci klonları bağlantı havuzunu ve token önbelleğini paylaşır. Token ihtiyaç olduğunda edinilir; eşzamanlı yenilemeler birleştirilir ve süre dolmadan yenilenir. Yapılandırma/istemci/doğrulayıcı Debug çıktıları secret'ları, yanıt Debug çıktısı gövdeyi gizler. data/raw erişimcileri müşteri bilgisi içerebilir; loglanmaz.

BaseURL yol, kullanıcı bilgisi ve sorgu içermeyen güvenilir HTTPS kökenidir. Yönlendirmeler, reqwest'in kendi tekrarları, ortam proxy'leri ve Referer aktarımı kapalıdır. İstek yolu köken değiştiremez, dizin aşamaz veya auth alanına giremez.

Checkout başlatma

Sipariş ve sepeti sunucu kayıtlarınızdan okuyun. Deneme anahtarını çağrıdan önce kaydedin; belirsiz sonucu aynı gövde ve anahtarla tekrar edin.

use lunixi::{BasketItem, IntentRequest};
 
let mut intent = IntentRequest::new(
    10050, "TRY", "ORD-1001", "https://merchant.example/payment/return",
);
intent.basket_items.push(BasketItem::new(
    "line-1", "Örnek ürün", "PHYSICAL", 10050,
));
let response = client.payments()
    .create_intent(&intent, &kayitli_deneme_anahtari).await?;
let token = response.data.as_ref()
    .and_then(|data| data.get("token"))
    .and_then(|value| value.as_str())
    .filter(|value| !value.is_empty())
    .ok_or(lunixi::Error::Response("checkout token eksik"))?;

Token yalnız ilgili siparişin yetkili müşterisine Cache-Control: no-store ile verilir; mevcut Lunixi formu açılır. Token URL, log ve analitik verisine yazılmaz. Form açık kart/alternatif yöntemleri gösterir; varsayılan SDK örnekleri ham kart toplamaz.

Tutarlar pozitif i64 kuruştur; en fazla 9007199254740991 kabul edilir. 10050 = 100,50 TRY. Sepet price alanı kalem toplamıdır ve toplam kök amount ile eşleşir. Kök ödeme toplamı tek tutar alanıdır; taksit/vade farkını form yönetir. Alıcı/adres ve belgelenmiş sigorta sepet alanları desteklenir. Yöntem kısıtlaması yalnız panelde açık yöntemleri daraltır. Option<bool> ile açık false değeri korunur.

Token, tarayıcı dönüşü, HTTP başarısı veya AUTHORIZED tahsilat kanıtı değildir. Gateway sonucunu doğrulayıp merchant/sipariş/ödeme kimliği, beklenen tutar/para birimi ve nihai tahsilat/uzlaştırma durumunu eşleştirmeden siparişi tamamlamayın. İade, iptal ve itiraz ayrı geçişlerdir.

API kapsamı

let refund = client.payments()
    .refund(&payment_id, Some(2500), Some("Müşteri iadesi"), &kayitli_iade_anahtari)
    .await?;

None tutar tam capture/refund ister. void provizyonu bırakır. Split güvenli bacak tutarlarını, 1–5 bacağı ve tam toplamı denetler; yöntem şeması gateway'de doğrulanır. Bekleyen split durumunda HTTP 400 içeren Response gelebilir; ödenmiş sayılmaz. Toplam/bacak dengeleri uzlaştırılır.

Yanıt envelope, data, page_info, ikili bytes, içerik tipi ve güvenli request ID'yi korur. decode_data::<T>() uygulamanızın şemalarına dönüşüm sağlar. JSON tam sayılar float'a çevrilmez. Hatalarda uzak sunucunun gövdesi/mesajı, URL veya secret bulunmaz.

0.1.1 sürümünde cüzdan, banka, ödeme linki, sigorta, pazaryeri, abonelik ve kimlik için ayrı tipli istemciler yoktur. Bu ürünlerin REST şemaları send ile kullanılır; tipli yardımcı eşitliği iddia edilmez.

use lunixi::{Method, Request};
let mut request = Request::new(Method::GET, "/api/v1/payments");
request.query.push(("limit".into(), "20".into()));
let response = client.send(request).await?;

Her merchant isteği imzalanır. Kanonik JSON, JavaScript sayısal anahtar sırasını ve ECMAScript sayı biçimini izler. Güvensiz tam sayılar, yinelenen JSON anahtarları ve aşırı iç içelik reddedilir. Token isteğinde gövde/Digest yoktur.

Bilinen ödeme mutasyonları ve finansal yardımcılar 16–128 karakterlik boşluksuz yazdırılabilir ASCII anahtar ister. Tekrarda gövde/anahtar aynı kalır, nonce yenilenir. Yalnız GET/anahtarlı istekler yapılandırılan sınırda tekrarlanır; anahtarsız mutasyon kör tekrarlanmaz. Yeni ödeme başlatmadan önce belirsiz sonucu uzlaştırın.

Ham webhook doğrulama

let verifier = lunixi::WebhookVerifier::new(vec![
    std::env::var("LUNIXI_WEBHOOK_SECRET")?,
])?;
let event = verifier.verify(ham_govde, basliklar)?;

Boyutu sınırlandırılmış ham baytlar JSON middleware'den önce doğrulanır. Başlık tipi reqwest::header::HeaderMap (HTTP 1.x) şeklindedir; framework dönüşümünde yinelenen kimlik başlıklarını gizlemeyin. HMAC-SHA256 event ID, zaman damgasının birebir metni ve ham baytları kapsar; sabit zamanlı karşılaştırılır. Varsayılan tolerans 5 dakika, izin verilen aralık 1–900 saniyedir ve kapatılamaz. İmzalı gövdede type gerekir. Başlık/JSON tekrarları ve ID/tür uyuşmazlığı reddedilir. En fazla üç güncel/önceki secret rotasyon sağlar.

İmza doğrulama event ID'yi tüketmez. sqlite özelliğini açıp kalıcı bağlantı kullanın:

let inbox = lunixi::SqliteInbox::new(merchant_scope)?;
lunixi::SqliteInbox::ensure_schema(&connection)?; // başlangıç / migration
let uygulandi = inbox.process(&mut connection, &event, |transaction| {
    dogrulanmis_siparisi_isle(transaction, &event)
})?;

connection, rusqlite::Connection bağlantınızdır. dogrulanmis_siparisi_isle, finansal alanları eşleyip verilen transaction içinde sipariş/outbox güncelleyen adaptörünüzdür. Senkron SQLite işi asenkron sunucuda blocking worker'a alınır. Olay kaydı ve iş durumu aynı transaction içinde commit edilir. Tekrar callback'i çalıştırmaz; aynı ID farklı gövdeyle gelirse reddedilir. Callback/depolama hatasında marker geri alınır; sağlayıcı güvenle tekrar teslim eder.

Merchant başına scope ayırın; kayıtları replay politikanız boyunca saklayın. Harici yan etkiler outbox worker'da yürütülür. Başka veritabanında aynı unique event/hash/iş güncellemesi transaction sözleşmesini uygulayın. Depolama hatasına HTTP 2xx dönmeyin. Eski olay için zamanı atlamak yerine panelden yeni replay isteyin.

Çalıştırılabilir kalıcı bildirim örneği (opens in a new tab), stdin ham gövdesini ve gerçek teslim başlıklarını doğrulayıp yalnız event ID/türünü kaydeder; siparişi tamamlamaz. TEST checkout örneği (opens in a new tab) token'ı konsola basmaz.

Kontroller

cargo fmt --all --check
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo audit
cargo deny --all-features check advisories licenses sources
cargo package --locked --allow-dirty --all-features

Testler gerçek yerel TLS, bağımsız Node.js JSON/Ed25519/HMAC vektörleri, eşzamanlı token edinimi ve SQLite geri alma/yeniden başlatma/tekrar durumlarını kapsar. Anahtarlar sentetiktir; canlı merchant çağrısı yapılmaz. Güvenlik politikası (opens in a new tab).

Mağaza içi entegrasyon örneği

Kaynak checkout örneği checkout_presentation.rs (opens in a new tab) dosyasını kullanır: render_checkout_html(token, nonce) resmi formu mount eder; hosted_checkout_url(paymentPageUrl) isteğe bağlı adresi doğrular. Kendi yetkili ve CSRF korumalı mağaza controller’ınıza uyarlayın. LUNIXI_CHECKOUT_MODE varsayılanı embedded, alternatif değer hosted olur. CLI üretilen HTML/token/URL verisini yazdırmaz. Bunlar kaynak örnek yardımcılarıdır; yeni ürün API’leri değildir.