Karar API'si

Fraud ürünü tek bir gerçek zamanlı karar ucu sunar. Bir işlemi (ve müşteri, cihaz, işyeri hakkında elinizdeki bağlamı) gönderirsiniz; milisaniyeler içinde, daha ödemeyi çekmeden allow / review / block / force_3d kararını açıklanabilir gerekçe setiyle alırsınız.

Taşıma ve gateway bağımsızdır: ödeme orkestratörümüzü kullanmanız gerekmez. Kendi gateway'i veya tek POS'u olan bir işyeri de, kendi alt-işyerlerini skorlayan bir ödeme kuruluşu (PSP) da aynı şekilde entegre olur.

Tüm örnekler için temel URL: https://api-gateway.lunixi.com/api/v1.

Kimlik Doğrulama

Fraud kararları Bearer erişim token'ı kullanır. Kayıtlı Ed25519 anahtarınızla POST /api/v1/auth/token'a imzalı istek atıp kısa ömürlü token alırsınız, sonra her karar çağrısında gönderirsiniz:

Authorization: Bearer <access-token>

İmza şeması (X-Key-Id, X-Date, X-Nonce, Digest, X-Signature) Kimlik Doğrulama sayfasında anlatılır. Token'ınız fraud:view_decisions kapsamını taşımalıdır. Kimliği doğrulanan taraf (sizin merchantId değeriniz) token'dan alınır, asla istek gövdesinden değil — gövde başka bir kiracıyı taklit edemez.

Uç (Endpoint)

POST /api/v1/fraud/decisions/evaluate

Aşağıdaki her alan opsiyoneldir — elinizde ne varsa gönderin. Motor yalnızca aktif kurallarının başvurduğu alanları okur; gerisi bağlam olarak saklanır. Tüm tutarlar minör-birim tam sayıdır (ör. 250000 = ₺2.500,00). Asla ondalık göndermeyin.

Yönlendirme alanları (üst seviye)

Kanal taksonomisi (üst seviye)

Bu alanlar isteğin nereden ve hangi anda geldiğini söyler. Akış tetikleyicileri bu boyutlarla eşleşir, karar kaydı bunları kolon olarak tutar ve raporlar bunlara göre kırılır. Hepsi opsiyoneldir, ama göndermek akışlarınızı daraltabilmenizi sağlar.

Obje sözlüğü

subjectType değerinize uyan objeleri gönderin. Besler sütunu, alanın desteklediği risk senaryosunu adlandırır (TCMB referansları Türkiye Cumhuriyet Merkez Bankası Risk Yönetimi Rehberi'ne aittir; aynı alanlar başka regülasyon paketlerinde eşdeğer kuralları çalıştırır).

payment — kart ödemesi

customer

device

session — ödemenin verildiği oturum bağlamı

Yönlendirilmiş ödeme (müşteriye telefonda anlatılan ödeme) sinyalleri buradan okunur. Göndermezseniz bu sinyaller "bilinmiyor" sayılır.

merchant — alt-işyeri bağlamı (PSP / kendi gateway'i)

Bunu, işyeri ilişkisinin sahibi siz olduğunuzda gönderin (ör. alt işyerlerini skorlayan bir ödeme kuruluşu). SaaS platformumuzu kullanıyorsanız ve göndermezseniz, MCC işyerinin kimlik bilgisinden çözülür.

bankTransfer — hesap / cüzdan transferleri

billPayment — fatura ödeme & para havalesi

Diğer işlem tipi payload'ları

walletOperation (walletId, operationType, amount, destinationWalletId), cryptoTransfer (asset, walletAddress, chain, travelRuleReference), loanApplication (requestedAmount, declaredIncome, employerName) ve payout (beneficiaryId, destinationType, destinationReference) aynı şekli izler — subjectType değerinize uyan objeyi gönderin; hangi alanların önemli olduğuna akışınızın kuralları karar verir.

telemetry, mobileApp, metadata

• telemetry — davranışsal sinyaller (mouseMovementCount, copyPasteCount, typingCadenceScore, behavioralRiskScore).
• mobileApp — mobil kimlik & attestation (installId, deviceId, platformScopedIdHash, playIntegrityToken, appAttestAssertion …).
• metadata — serbest bağlam. Sunucuda türetilen sinyaller (işlem-açıklaması kelime bayrakları, back-URL uyumsuzluğu, IP ülkesi, telefon hash'i) event ingest sırasında hesaplanır ve kurallara metadata.fraudTransactionEvent.* altında sunulur.

Yanıt

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "decision": "allow | review | block | force_3d",
    "score": 0.42,
    "reasonCodes": ["TCMB_3.1.2_6"],
    "matchedRuleGroups": [],
    "matchedRules": [],
    "flowPath": [],
    "actions": [],
    "tags": [],
    "explainability": { "summary": "", "groupResults": [] },
    "liveSignals": {},
    "multiFlow": {
      "enabled": true,
      "executedFlows": [],
      "skippedFlows": [],
      "asyncFlows": []
    },
    "traceId": "…",
    "latencyMs": 12
  },
  "statusCode": 200,
  "requestId": "req_01J8ZV..."
}

decision değerini yetkili kabul edin. reasonCodes ve explainability her kararı denetim için belgeler. multiFlow bloğu hangi akışların koştuğunu, hangilerinin atlandığını ve hangilerinin arka planda kuyruğa alındığını gösterir — ayrıntı: Akışlar ve Çözümleme.

traceId kararın tekil kimliğidir. Kararı sonradan okumak ya da bir destek talebinde göstermek için saklamanız gereken tek değer budur — bkz. Karar Kayıtları.

Hata kodları, kota yanıtı ve yeniden deneme kuralları: Hatalar, tekrarlı istekler ve yeniden deneme.

Örnek

curl https://api-gateway.lunixi.com/api/v1/fraud/decisions/evaluate \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "card_payment",
    "paymentRail": "card",
    "paymentId": "pi_123",
    "payment":  { "amount": 250000, "currency": "TRY", "id": "hmac:card-fingerprint" },
    "customer": { "id": "cus_88", "email": "[email protected]", "isNew": true },
    "device":   { "fingerprintId": "dev_9f2c", "ipAddress": "203.0.113.7" },
    "merchant": { "merchantRef": "sub_88", "mcc": "7995", "country": "TR", "onboardingDate": "2026-06-01" }
  }'

Sayan kurallar için geçmiş besleyin

Tek bir evaluate çağrısı yalnız önündeki işlemi bilir. Zamanla sayan kurallar — "bugün 10'dan fazla transfer", "5'ten fazla farklı alıcı", sektör ortalamasına göre ciro sapması — geçmişe ihtiyaç duyar. Geçmişi olay omurgasına beslersiniz:

POST /api/v1/fraud/events/transactions         (tekil)
POST /api/v1/fraud/events/transactions/batch   (parti)

Bu uçlar Bearer token yerine istek başına Ed25519 imzası kullanır ve senkron yazar: sonraki evaluate çağrısı olayı anında görür. Kendi tarafınızda bir mesaj kuyruğuna ihtiyacınız yoktur.

Zorunlu alanlar, olay türü sözlüğü, parti sınırları ve imza ayrıntıları: Olay Alımı API'si.