Java SDK

com.lunixi:lunixi-java-sdk, Lunixi'nin Java istemcisidir. İstek imzalama, token alışverişi, yanıt zarfının okunması ve imleçli sayfalama SDK'dadır.


Java	17 ve üzeri
Çalışma zamanı bağımlılığı	yok
Lisans	MIT

Kapsam

Bileşen	İşlevi
`LunixiConfig`	Değişmez, kurulurken doğrulanan yapılandırma
`auth.Ed25519KeyPair` · `Ed25519Signer`	Anahtar çifti üretme, istek imzalama
`auth.TokenManager` · `TokenStore`	İmzalı token alışverişi ve token önbelleği
`http.HttpTransport` · `JdkHttpTransport`	Değiştirilebilir HTTP taşıyıcısı
`fraud.FraudClient`	Fraud kararı, karar kayıtları ve olay alımı
`webhook.WebhookVerifier`	Gelen webhook'ların fail-closed doğrulanması
`exception.*`	Tipli hata ailesi

Java SDK'sı bu sürümde fraud yüzeyini ve webhook doğrulamayı içerir. Ödeme ve diğer ürünler için SDK'sız REST akışını kullanabilirsiniz; istek katmanı aynıdır.

Kurulum

Gradle:

implementation 'com.lunixi:lunixi-java-sdk:0.1.0'

Maven:

<dependency>
  <groupId>com.lunixi</groupId>
  <artifactId>lunixi-java-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

SDK'nın çalışma zamanı bağımlılığı yoktur: imza, HMAC, HTTP ve JSON JDK ile karşılanır, sınıf yolunuzdaki kütüphanelerle sürüm çatışması çıkmaz.

Anahtar çifti

Ed25519KeyPair keyPair = Ed25519KeyPair.generate();
// keyPair.publicKeyPem()  → panele yükleyin
// keyPair.privateKeyPem() → sır yöneticinizde saklayın

Özel anahtarı kaynak koda yazmayın ve loglara düşürmeyin.

İstemciyi oluşturma

LunixiClient client = LunixiClient.create(LunixiConfig.builder()
        .baseUrl("https://api-gateway.lunixi.com")
        .keyId(System.getenv("LUNIXI_KEY_ID"))
        .privateKey(System.getenv("LUNIXI_PRIVATE_KEY"))
        .environment(LunixiConfig.Environment.TEST)
        .build());

İstemciyi bir kez kurup saklayın. Değişmezdir, iş parçacıkları arasında paylaşılabilir ve token önbelleğini taşır. Builder ayrıca timeout(Duration), maxRetries(int), transport(HttpTransport) ve tokenStore(TokenStore) alır.

Fraud kararı

FraudDecision decision = client.fraud().evaluate(EvaluateRequest.create()
        .standaloneIntegrationMode()
        .channel(FraudTaxonomy.Channel.STANDALONE_API)
        .productContext(FraudTaxonomy.ProductContext.DIRECT_API)
        .transactionRef("order-2026-0001")
        .payment(Map.of("amount", 25000, "currency", "TRY"))
        .customer(Map.of("email", email, "country", "TR"))
        .device(Map.of("ipAddress", ipAddress)));
 
if (decision.isBlock()) {
    // işlemi reddedin
} else if (decision.isForce3d()) {
    // 3D Secure ile yeniden deneyin
}

Lunixi üzerinden alınan bir ödemede karar yetkilendirme sırasında zaten üretilir; ikinci kez sormak yerine kaydından okuyun:

Optional<FraudDecision> recorded = client.fraud().decisions().latestForPayment(paymentId);

evaluate, kendi olaylarınızı (kayıt, giriş, para çekme, kendi sağlayıcınızla yetkilendirdiğiniz bir ödeme) taramak içindir. → Fraud

Karar kayıtları

for (FraudDecision record : client.fraud().decisions()
        .iterate(DecisionLogFilter.create().limit(100))) {
    // sayfalar imleç izlenerek çekilir
}

İmleç opaktır: çözmeyin, üretmeyin, değiştirmeyin; bir sonraki istekte aynen geri gönderin.

Olay alımı

client.fraud().events().record(Map.of(
        "eventId", "evt-0001",
        "eventType", "card_payment",
        "subjectType", "customer",
        "occurredAt", "2026-10-11T08:00:00Z"));
 
FraudEventBatchResult batch = client.fraud().events().recordBatch(events);
if (!batch.failures().isEmpty()) {
    // reddedilen olayları düzeltip aynı eventId ile yeniden gönderin
}

Bir parti en çok 500 olay taşır; daha büyük parti ağa çıkmadan reddedilir. Parti kısmen başarılı olabilir: uç 200 döner, reddedilen olaylar failures() listesindedir. Aynı eventId ile yeniden gönderim güvenlidir.

Webhook doğrulama

WebhookEvent event = new WebhookVerifier().verify(rawBody, headers, endpointSecret);

rawBody gövdenin ham hâli olmalıdır; JSON'u ayrıştırıp yeniden seri hâle getirirseniz baytlar değişir ve teslimat doğrulanamaz. Doğrulama fail-closed çalışır, her uyuşmazlıkta istisna fırlatır. Fraud olay tipleri FraudEvents sabitlerindedir.

Hatalar

Sınıf	Durum
`ValidationException`	`400` / `422` — gövde reddedildi
`AuthenticationException`	Token alınamadı (imza, anahtar, IP)
`RateLimitException`	`429` — `retryAfter()`
`ServiceUnavailableException`	`503` — `retryAfter()`
`LunixiApiException`	Diğer hata yanıtları ve taşıma hataları
`ConfigurationException`	Yerel doğrulama; ağa çıkılmadan önce
`SignatureException`	Anahtar okunamadı ya da imzalanamadı
`WebhookVerificationException`	Webhook doğrulanamadı

Dallanmayı code() üzerinden yapın; mesaj metni değişebilir.

Yeniden deneme

401: token yenilenir ve istek bir kez yeniden gönderilir.
Taşıma hatası ya da 5xx: yalnız okuma veya idempotency anahtarı taşıyan çağrılar yeniden denenir.
Diğer 4xx: yeniden denenmez.

İlgili

Fraud — karar modeli ve olay alımı
Kimlik Doğrulama — anahtar, imza ve token ömrü
SDK'sız REST — SDK'nın kapsamadığı uçlar

PHP Python