Olay Alımı API'si

Karar API'si yalnız önündeki işlemi görür. Zamanla sayan kurallar — "bugün 10'dan fazla transfer", "ayda 5'ten fazla farklı alıcı", kendi cironuza göre sapma — bir geçmişe ihtiyaç duyar. O geçmişi bu uçlarla beslersiniz.

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

Kimlik doğrulama — istek başına imza

Her istekte şu başlıklar bulunur:

Kanonik dizge satırları \n ile birleştirilir:

POST
/api/v1/fraud/events/transactions
X-Date:2026-10-05T09:12:44.000Z
X-Nonce:5f1c9a6e-7b2d-4a11-9c3e-2f8a7d41b0c6
Digest:SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

• İlk satır HTTP yöntemi (büyük harf), ikinci satır sorgu dizesi dahil yoldur.
• Digest satırı yalnız Digest başlığı gönderildiğinde eklenir.

Anahtarınızın ayrıca FRAUD_SERVICE ürün yetkisi olmalıdır; olmazsa uç 403 döner. Anahtara IP kısıtı tanımladıysanız istek o adreslerden gelmelidir.

Tekil olay

POST /api/v1/fraud/events/transactions

Zorunlu alanlar

Bağlam alanları

Hepsi opsiyoneldir; elinizde olanı gönderin. Bir alanı göndermemek onu "bilinmiyor" yapar.

• amountMinor minör birim tam sayıdır (250000 = ₺2.500,00). Ondalık göndermeyin.
• operationKind ve direction gibi sözlüklü alanlarda sözlük dışı bir değer 400 döner — bir yazım hatası bir kuralı sessizce ıskalamasın.
• relatedEventId en fazla 180 karakterdir.

Karşı taraf zorunluluğu

Şu olay türleri bir karşı tarafa değer taşır; counterparty göndermezseniz istek 400 döner:

transfer_requested · transfer_completed · withdrawal_requested · withdrawal_completed

subjectType ya da productContext mobile_payment değerini taşıyorsa phone zorunludur: operatör tahsilatında hesap anahtarı telefon numarasıdır.

Tekrar bastırma

Aynı hesap için aynı eventId ikinci kez gönderilirse olay yeniden yazılmaz; yanıt o olayı deduplicated: true ile bildirir. Bu, yeniden deneme güvenliği sağlar: bir zaman aşımından sonra aynı olayı aynı eventId ile tekrar gönderebilirsiniz.

Örnek

BODY='{"eventId":"evt_8812","eventType":"transfer_completed","subjectType":"transaction","occurredAt":"2026-10-05T09:12:40.000Z","customerId":"cus_88","counterparty":"TR330006100519786457841326","amountMinor":250000,"currency":"TRY","ip":"203.0.113.7","direction":"outbound"}'
DIGEST="SHA-256=$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | openssl base64 -A)"
 
curl https://api-gateway.lunixi.com/api/v1/fraud/events/transactions \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-Nonce: $(uuidgen)" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

Yanıt

{
  "status": "success",
  "code": "SUCCESS",
  "message": "...",
  "data": {
    "eventId": "evt_8812",
    "id": "a3f1c0d2-...",
    "deduplicated": false,
    "matchedFlowCount": 2
  },
  "statusCode": 200,
  "requestId": "req_01J8ZV..."
}

• id yalnız gerçekten satır yazıldığında döner; tekrar bastırmada gelmez.
• matchedFlowCount, bu olayla eşleşen ve koşan akış sayısıdır.

Parti

POST /api/v1/fraud/events/transactions/batch

Gövde ya doğrudan bir JSON dizisi ya da { "events": [...] } nesnesidir. İkisi de olmayan bir gövde 400 FRAUD_EVENT_BATCH_INVALID döner — boş bir parti sessizce "0 kayıt başarılı" sayılmaz.

Parti sırayla işlenir ve kısmen başarılı olabilir: bir olayın doğrulaması düşerse diğerleri yazılmaya devam eder.

{
  "status": "success",
  "data": {
    "total": 3,
    "inserted": 2,
    "deduplicated": 0,
    "failed": 1,
    "results": [
      { "eventId": "evt_1", "id": "…", "deduplicated": false },
      { "eventId": "evt_2", "id": "…", "deduplicated": false },
      { "eventId": "evt_3", "deduplicated": false, "error": "Event is missing required field(s): occurredAt." }
    ]
  }
}

results dizisini her zaman okuyun: HTTP durumu 200 olsa da failed sıfırdan büyük olabilir. Düşen olayları error metnine göre düzeltip aynı eventId ile yeniden gönderebilirsiniz.

Olay türü sözlüğü

Sözlük dışı bir eventType 400 döner. Bu bilinçlidir: transfer_requsted gibi bir yazım hatası sessizce kabul edilse, o olayı sayan kural hiç tetiklenmez ve eksiklik aylarca görünmezdi.

Hesap ve oturum

account_created · account_closed · account_restricted · relationship_terminated · login_succeeded · login_failed · otp_failed · pin_failed · password_changed · phone_changed · email_changed · device_registered

Ödeme

payment_attempted · payment_completed · payment_failed · refund · chargeback · chargeback_reversed · authentication_completed

Transfer, çekim ve havale

transfer_requested · transfer_completed · withdrawal_requested · withdrawal_completed · beneficiary_created · settlement_requested

Fatura ödeme

bill_payment · bill_query

İşyeri ve hesap bütünlüğü

merchant_iban_changed · domain_changed · api_key_created · api_request

Yönlendirilmiş ödeme bağlamı

Bunlar para hareketi değildir; bir ödemenin çevresindeki olgulardır. Mevcut eşikleri değiştirmezler, yalnız kendilerini adıyla okuyan kurallara girerler.

payee_confirmation_checked · payee_confirmation_requested · scam_warning_presented · scam_warning_acknowledged · scam_hold_applied · scam_hold_released · app_scam_reported · app_scam_claim_notified

Bu ailede bazı alanlar zorunludur:

Eksik alan 400 döner: bir uyarının hangi ödemeye ait olduğu kayıtta yoksa, "uyarı gösterildi mi" sorusu sonradan cevaplanamaz.

Sektör ortalaması kuralları için

Kendi cironuza göre sapma kuralları yalnız kendi geçmişinizi okur ve ek alan istemez. Sektör ortalaması karşılaştırması ise sektör kırılımına ihtiyaç duyar: olaylara işyerinin MCC değerini metadata.mcc altında ekleyin. MCC taşımayan olaylar kendi-geçmiş kurallarını beslemeye devam eder, yalnız sektör karşılaştırması veri bulamaz.

Hata ve kota

Alım, kota reddini Retry-After başlığıyla döndürür ve olay kaybolmaz: başlıktaki süre kadar bekleyip aynı eventId ile yeniden gönderin. Durum kodları, hata kodları ve kota başlıkları: Hatalar, tekrarlı istekler ve yeniden deneme.

Sonraki adım

• Karar API'si — ödeme anında karar
• Karar Kayıtları — verilmiş kararları okuma ve mutabakat
• Akışlar ve Çözümleme — hangi akışın hangi olayla tetiklendiği