Decision API

The Fraud product exposes a single real-time decision endpoint. You send a transaction (and whatever context you have about the customer, device and merchant) and receive an allow / review / block / force_3d decision with an explainable reason set — in milliseconds, before you charge.

It is transport- and gateway-agnostic: you do not need to use our payment orchestrator. A merchant with its own gateway or a single POS, or a payment institution (PSP) scoring its own sub-merchants, integrates the same way.

Base URL for all examples: https://api-gateway.lunixi.com/api/v1.

Authentication

Fraud decisions use a Bearer access token. Obtain a short-lived token by signing a request to POST /api/v1/auth/token with your registered Ed25519 key, then send it on every decision call:

Authorization: Bearer <access-token>

The signing scheme (X-Key-Id, X-Date, X-Nonce, Digest, X-Signature) is described in Authentication. Your token must carry the fraud:view_decisions scope. The authenticated party (your merchantId) is taken from the token, never from the request body — the body cannot spoof a different tenant.

Endpoint

POST /api/v1/fraud/decisions/evaluate

Every field below is optional — send what you have. The engine reads exactly the fields your active rules reference; anything else is stored as context. All amounts are minor-unit integers (e.g. 250000 = ₺2.500,00). Never send decimals.

Routing fields (top level)

Channel taxonomy (top level)

These fields say where and at which moment the request came from. Flow triggers match on these dimensions, the decision record keeps them as columns, and reports break down by them. All are optional, but sending them is what lets you narrow your flows.

Object dictionary

Send the object(s) that match your subjectType. The Feeds column names the risk scenario the field supports (TCMB references map to the Turkish Central Bank Risk Management Guide; the same fields drive equivalent rules in other regulatory packs).

payment — card payment

customer

device

session — the session the payment was made in

Authorised push payment signals (a payment talked through on the phone) are read from here. If you do not send it, these signals count as "unknown".

merchant — sub-merchant context (PSP / own-gateway)

Send this when you own the merchant relationship (e.g. a payment institution scoring its sub-merchants). If you use our SaaS platform and omit it, MCC is resolved from the merchant's credential.

bankTransfer — account / wallet transfers

billPayment — bill payment & remittance

Other subject-type payloads

walletOperation (walletId, operationType, amount, destinationWalletId), cryptoTransfer (asset, walletAddress, chain, travelRuleReference), loanApplication (requestedAmount, declaredIncome, employerName) and payout (beneficiaryId, destinationType, destinationReference) follow the same shape — send the object that matches your subjectType; your flow's rules decide which fields matter.

telemetry, mobileApp, metadata

• telemetry — behavioral signals (mouseMovementCount, copyPasteCount, typingCadenceScore, behavioralRiskScore).
• mobileApp — mobile identity & attestation (installId, deviceId, platformScopedIdHash, playIntegrityToken, appAttestAssertion …).
• metadata — any free-form context. Server-derived signals (transaction-description keyword flags, back-URL mismatch, IP country, phone hash) are computed at event ingest and exposed to rules under metadata.fraudTransactionEvent.*.

Response

{
  "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..."
}

Treat decision as authoritative. reasonCodes and explainability back every decision for audit. The multiFlow block shows which flows ran, which were skipped and which were queued in the background — details: Flows and Resolution.

traceId is the decision's unique id. It is the only value you need to store to read the decision later or quote it in a support request — see Decision Logs.

Error codes, the quota response and the retry rules: Errors, repeated requests and retries.

Example

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" }
  }'

Feed history for rules that count

A single evaluate call knows only the transaction in front of it. Rules that count over time — "more than 10 transfers today", "more than 5 distinct recipients", a turnover deviation from the sector average — need history. You feed that history to the event backbone:

POST /api/v1/fraud/events/transactions         (single)
POST /api/v1/fraud/events/transactions/batch   (batch)

These endpoints use a per-request Ed25519 signature instead of a bearer token, and they write synchronously: the next evaluate call sees the event immediately. You do not need a message queue on your side.

Required fields, the event-type vocabulary, batch limits and the signing details: Event Ingest API.