API dokümanı

Fraud tespit API: her ödemeyi ödeme kuruluşundan önce skorlayın

Bir fraud tespit API’si ödeme, müşteri ve cihaz verilerini alır ve gerçek zamanlı olarak risk skoru ile öneri döner. RiskCogs ile ödeme sayfasında tarayıcı SDK’sını yükler, sunucudan oturum ve siparişi POST /v1/risk-score’a gönderir, öneriye göre hareket eder ve sonucu geri bildirirsiniz.

Shadow modunda ücretsiz başlayın

1. Tarayıcı SDK’sını ödeme sayfasında yükleyin

SDK, kullanıcı onayıyla cihaz ve oturum bağlamını toplar ve sunucunuz için bir oturum kimliği döner. Endpoint ve anahtar RiskCogs konsolundadır.

import { RiskCogs } from '@fraud/sdk-browser';

const risk = await RiskCogs.init({ endpoint: 'https://YOUR_RISKCOGS_INTAKE_HOST', publicKey: 'pub_YOUR_PUBLISHABLE_KEY' });
// On checkout submit: pass the session to your server score request.
const { sessionId } = await risk.getContext();

2. Ödemeyi sunucu tarafında skorlayın

Ödemeyi ödeme kuruluşuna göndermeden önce API’yi çağırın. Node 18 ve üzeri ek kütüphane gerektirmez.

// Server only: the secret (pr_*) key never reaches a browser.
const res = await fetch('https://YOUR_RISKCOGS_API_HOST/v1/risk-score', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RISKCOGS_SECRET_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    requestId: order.id, flowType: 'checkout',
    email: order.email, ip: clientIp, sessionId: order.riskcogsSessionId,
    money: { amount: order.total, currency: order.currency }, // decimal string, major units
  }),
});
const { riskId, risk_score, level, recommendation, shadowMode } = await res.json();
// Keep riskId: send it with the outcome to POST /v1/risk-feedback later.

3. Ya da curl ile deneyin

curl -X POST https://YOUR_RISKCOGS_API_HOST/v1/risk-score \
  -H "X-API-Key: $RISKCOGS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"quickstart-test-1","flowType":"checkout","email":"[email protected]","ip":"203.0.113.45","money":{"amount":"49.00","currency":"EUR"}}'

4. Yanıtı okuyun ve uygulayın

recommendation alanıyla ödemeyi yönlendirin: onay, inceleme veya ret. Shadow modunda öneriyi kaydedin, akışınızı değiştirmeyin.

{
  "riskId": "0190f3c2-…",
  "risk_score": 18,
  "level": "low",
  "recommendation": "allow",
  "shadowMode": true,
  "flags": [],
  "signals": { "email": { … }, "ip": { … } }
}

Anahtarlar, tutarlar ve geri bildirim

İki anahtar: tarayıcı SDK’sı için pub_, sunucu için pr_. Gizli anahtar tarayıcıya asla ulaşmaz.
Tutarlar para birimiyle ondalık metin olarak, örn. "49.00" EUR.
Yanıt riskId, risk_score, level, recommendation, shadowMode, flags ve signals içerir.
riskId’yi saklayın ve sonucu POST /v1/risk-feedback’e gönderin.
Varsayılan eşikler: 40’ın altı onay, 40–69 inceleme, 70 ve üzeri ret.

Sıra diyagramı: ödeme sayfasında SDK, sunucudan POST /v1/risk-score çağrısı, skor ve gerekçeler, ardından POST /v1/risk-feedback geri bildirimi

Sık sorulan sorular

Fraud tespit API’si nedir?

Ödeme, hesap veya giriş verisini alıp skor ve önerilen aksiyon döndüren bir web servisi.

Ödeme akışında nerede çağrılır?

Sipariş gönderildikten sonra ve ödeme kuruluşundan önce, sunucu tarafında; SDK oturum kimliğiyle birlikte.

Sonuçlar neden bildirilmeli?

Skorun hangi ödemelerin iyi, iade veya ters ibraz olduğunu öğrenmesi için.

Birden çok ödeme kuruluşuyla çalışır mı?

Evet, skor herhangi bir kuruluştan önce hesaplanır.

İlgili yazılar

Önce ölçün. Sonra engelleyin.

RiskCogs’u mevcut ödeme sağlayıcınızın yanında shadow modunda çalıştırın ve kararları tek bir müşteriyi etkilemeden önce inceleyin.

Shadow modunda ücretsiz başlayın