Anti-fraud API: real-time fraud detection and behavioral risk scoring

The structure of an anti-fraud API

The architecture of modern anti-fraud systems is built on the principles of a REST API — a standard that ensures predictable interaction between the client application and the verification server. A fraud detection API receives data about a transaction or user, processes it through machine learning algorithms, and returns a structured response with a risk assessment. This approach makes it possible to integrate the check at any point in the customer journey: from registration and authorization to the moment of payment.

The key requirement for the structure of a risk scoring API is minimal latency with maximum informativeness of the response. The system must process a request in tens of milliseconds so as not to create noticeable pauses in the user scenario. At the same time, the response contains not just a binary “approve” or “decline” decision but a detailed assessment indicating the factors that influenced the final score.

A real-time fraud API works in synchronous mode: the client sends a request and receives a response within a single HTTP session. For scenarios requiring in-depth analysis (checking against multiple external databases, complex behavioral analytics), an asynchronous model is provided with the deferred receipt of results through a separate endpoint or a webhook notification.

Endpoints and methods

The typical structure of an anti-fraud API includes several functional endpoints, each of which is responsible for a certain type of check.

Request authentication is implemented through API keys transmitted in the Authorization header, or through OAuth 2.0 tokens for scenarios with delegated access. All requests are processed exclusively over the HTTPS protocol — the transmission of sensitive data over an unprotected channel is unacceptable.

Request and response formats

Data exchange between the client and the anti-fraud API is carried out in the JSON format — a universal standard for web services that ensures readability for developers and efficient parsing for machines.

The structure of a request to the risk scoring API includes several logical blocks. The transaction block contains the amount, currency, order identifier, and timestamp. The device block transmits the fingerprint, IP address, User-Agent, and session data. The user block includes the account identifier, email, phone, and activity history. The payment instrument block contains hashed or masked card data, the BIN code, and the results of the AVS/CVV checks.

An example of a minimal request to the fraud detection API:

{
  "transaction_id": "ord_7834921",
  "amount": 15000,
  "currency": "RUB",
  "ip_address": "185.76.xx.xx",
  "device_fingerprint": "fp_a3b8c...",
  "user_id": "usr_44521"
}

The API response returns a numeric risk indicator (fraud score or risk score), the decision category, and a breakdown of the factors. The numeric score is usually presented in the range from 0 to 100, where low values indicate minimal risk, while values above 75–90 signal a high probability of fraud.

The decision category takes one of three values: approve, reject, or review (send for manual review). Some systems return more granular statuses or allow the threshold values for each category to be configured.

An example of the response structure:

{
  "request_id": "req_9a2f3e71",
  "risk_score": 23,
  "decision": "approve",
  "risk_factors": [
    {"code": "DEVICE_KNOWN", "impact": -15},
    {"code": "NEW_EMAIL_DOMAIN", "impact": +8}
  ],
  "processing_time_ms": 47
}

The risk_factors block reveals the decision-making logic: which signals lowered the risk score (a familiar device, a positive user history) and which raised it (a new email domain, a geolocation mismatch). This transparency is critical for debugging the integration and analyzing disputed cases.

The HTTP response codes follow standard semantics: 200 OK upon successful processing, 400 Bad Request for input data validation errors, 401 Unauthorized for authentication problems, 429 Too Many Requests when request limits are exceeded. A 5xx code signals internal service errors and requires resending the request.

For critical integrations, the API returns a Retry-After header indicating the recommended interval until the next attempt, as well as a unique request_id for tracing the request in logs and support requests.

Real-time fraud detection

The speed of decision-making determines the effectiveness of the anti-fraud system. Payment processors require a response within 100 milliseconds, otherwise the user will feel a delay and the business will lose conversion. The fraud detection API solves this task by analyzing transactions directly at the moment they are made and issuing a verdict before the operation is completed.

Traditional systems react after the fact: they detect fraud hours or days later, when the money has already been withdrawn. A real-time fraud API works differently — it assesses risk during authorization and blocks suspicious operations before damage is done. According to the Global Anti-Scam Alliance for 2025, global losses from fraud reached $442 billion, with the bulk falling on digital channels, where the time between the initiation and completion of a payment is measured in seconds.

Transaction analysis parameters

The fraud detection API accepts a set of transaction attributes and returns a risk assessment. The input parameters can be divided into four categories: financial, identification, behavioral, and contextual.

Financial parameters include the payment amount, currency, operation type, and merchant category. The system compares the current amount with the user’s historical patterns: a purchase of $5,000 at 3 a.m. with usual spending of up to $100 immediately raises the risk score.

Identification parameters cover everything related to the device and network: IP address, device fingerprint, geolocation, browser data, system language. The reputation of the IP is analyzed separately — whether the address belongs to a data center, VPN, proxy, or known fraud networks. According to payment systems, up to 80% of organizations encountered payment fraud in 2023, and a significant part of the attacks went through anonymized channels.

Velocity parameters track the frequency of events over a period: the number of transactions from one IP per hour, the number of failed login attempts over 10 minutes, the amount of purchases from one card per day. Velocity checks are one of the key tools against card testing, when fraudsters check stolen cards with a series of small payments.

Contextual parameters add information about the user session: the time since the last activity, the match of the delivery address with the billing address, the history of the customer’s relationship with the platform. Data enrichment from external sources — checking the email for a link to social networks, the age of the email domain, the presence of a phone number in leak databases — improves the accuracy of the assessment.

A typical API request contains 20–50 parameters. The minimum set includes the user identifier, the amount, the IP address, and the device ID. The extended set adds billing data, session history, and the results of previous checks.

Real-time detection logic

The architecture of real-time fraud detection is built on the parallel processing of several layers of analysis. The request simultaneously passes through a rule-based engine, ML models, and velocity counters, after which the results are combined into a final assessment.

The rule-based component applies deterministic rules: block transactions from certain countries, decline payments above a threshold without additional verification, flag operations from new devices. Rules are transparent, easy to audit, and quickly updated when new fraud schemes appear.

ML models analyze patterns unavailable to static rules. Supervised models are trained on historical data about confirmed fraud, unsupervised ones detect anomalies relative to the user’s normal behavior. According to research from 2024–2025, machine learning provides a detection accuracy of up to 99.1% while reducing false positives by 40–60% compared with rule-based systems.

Velocity analysis works through sliding-window counters. The system tracks aggregates such as “the amount of purchases from this device ID in the last hour” or “the number of unique cards from this IP per day”. Exceeding the thresholds adds points to the risk score or directly triggers a block.

Response time is critically important. Deep learning models show an average latency of about 80 ms, while modern architectures with edge computing achieve sub-millisecond speed on inference. Data enrichment — queries to external IP reputation services, device fingerprint checking — is performed asynchronously and cached to minimize delays.

The entire cycle — receiving the request, enrichment, parallel analysis, aggregation of results, formation of the response — fits within a budget of 50–100 ms for production systems. Under peak loads, for example during sales periods, platforms process millions of requests per minute without degradation of quality.

Threshold values and API decisions

The fraud detection API returns not a binary verdict but a numeric risk score — usually in the range of 0–100 or 0–1000. Low values indicate a legitimate transaction, high ones a probable fraud. Based on the score, the system makes one of three decisions: approve, review, or decline.

Approve is applied to low-risk transactions. The operation goes through without additional checks, and the user experiences no friction. The typical threshold is a score below 20–30 out of 100.

Review sends the transaction for a manual check or requests additional verification: an SMS code, 3D Secure, confirmation via a push notification. The review range usually covers a score of 30–70. The task of this level is to minimize false positives without letting real fraud through.

Decline blocks the operation automatically at a score above 70–80. The transaction is rejected, the card may be blocked for subsequent attempts, and the event is logged for analysis.

The specific thresholds are configured for the business model. A conservative strategy (minimizing fraud) sets low thresholds for decline, risking the loss of some legitimate customers. An aggressive strategy (maximizing conversion) raises the thresholds, accepting more risk. The optimal balance is found through A/B testing and the analysis of metrics: fraud rate, false positive rate, approval rate, chargeback rate.

In addition to the numeric score, the API returns risk factors — the specific signals that influenced the assessment: a suspicious IP, a geolocation mismatch, exceeding velocity limits. This information helps fraud analysts during manual review and is used for tuning the rules.

Modern systems support the dynamic calibration of thresholds. ML models are retrained on fresh data, and the thresholds are adjusted automatically as the fraud landscape changes. According to the industry, banks and fintech companies with AI-powered fraud detection demonstrate a 15–20% reduction in losses while simultaneously increasing the approval rate through the reduction of false positives.

Behavioral risk scoring

Transaction data records what exactly is happening: the transfer amount, the time of the operation, the geography of the participants. But it is unable to answer the fundamentally important question — who is behind the action? Behavioral risk scoring fills this gap by analyzing not the operations but the manner in which they are performed. Each user forms a unique digital handwriting: the rhythm of typing, the trajectory of cursor movement, the speed of navigation between interface elements. The fraud detection API converts these patterns into a numeric trustworthiness assessment, making it possible to identify fraudsters even before a suspicious action is completed.

Unlike rules that trigger upon the fact of a threshold being crossed, behavioral analysis works proactively. It records deviations from the norm in real time and adjusts the risk score dynamically — with each new session event. This approach is especially effective against sophisticated attacks: account takeovers, synthetic identities, and social engineering, where the attacker has all the victim’s formal details.

Behavioral signals for analysis

The anti-fraud API collects hundreds of parameters that form the user’s behavioral profile. All signals can be divided into three categories: the physical characteristics of interaction, the session context, and anomalies of transactional activity.

Modern risk scoring APIs analyze more than 3,000 contextual signals simultaneously, forming a multidimensional profile that fraudsters are unable to reproduce even with all of the victim’s credentials.

Calculating the risk score

Forming the risk assessment happens in several stages. First the system collects raw data about the event, then enriches it with external sources, after which it passes it to the scoring engine to calculate the final value.

Data collection and enrichment. With each user action — authorization, password change, payment — the API records the available parameters: IP address, device characteristics, behavioral metrics. Then the information is enriched from external databases: the reputation of the email domain, the history of the IP address, and the presence of the device on blacklists are checked. This stage is critically important, since local data may not contain signs of a threat visible only in the global context.

Applying the scoring models. Data processing is carried out by two parallel methods:

1. Rules with weighting coefficients. Each factor is assigned a score, positive or negative. For example, a match of the device with a previously used one reduces the risk (−5 points), while a login from a data center raises it (+15 points). The sum of all the weights forms a preliminary assessment. The advantage of this approach is full transparency: the analyst sees exactly which factors influenced the result.
2. Machine learning models. Random Forest algorithms, gradient boosting, and neural networks are trained on historical data where the outcomes of operations are already known. They identify non-linear dependencies unavailable to rules: for example, that the combination “new email + old device + large amount + nighttime” is more dangerous than each of the factors separately. ML models adapt to new fraud schemes faster than expert rules, but require regular re-evaluation on fresh data.

Modern fraud detection APIs use an ensemble approach, combining both methods. Rules provide interpretability and compliance with regulatory requirements, while machine learning provides accuracy and adaptability.

Normalization and calibration. The final value is brought to a single scale — most often from 0 to 100, where 0 means minimal risk and 100 maximal. Calibration guarantees that a score of 70 corresponds to approximately the same probability of fraud regardless of the operation type, channel, or customer segment. Without calibration, the threshold values would have to be set separately for each scenario, which complicates the operation of the system.

Calculation speed. A real-time fraud API must deliver a result in a time imperceptible to the user. The industry standard is less than 100 milliseconds for the full cycle: from receiving the request to returning the decision. This is achieved through a streaming architecture, precomputed features, and edge computing that brings the processing closer to the data source.

Interpreting the scoring results

A numeric assessment is useless in itself without the rules for applying it. The interpretation of the risk score determines what decision the system will make and how much this decision will affect the customer experience.

Risk zones. Standard practice divides the scale into three ranges:

• Low risk (0–30). The operation is performed automatically without additional checks. The user experiences no friction — payment goes through in one click, logging into the account takes seconds. The absolute majority of legitimate transactions fall into this zone.
• Medium risk (31–70). The system requests additional verification: a one-time code by SMS, biometric confirmation, an answer to a security question. The goal is to make sure that the real account owner is behind the action, without blocking the operation entirely.
• High risk (71–100). The transaction is rejected automatically or passed for manual analysis. In critical scenarios — for example, when an account takeover is suspected — a temporary block with a notification to the customer may be initiated.

The boundaries of the ranges are not universal. A business with a high margin and a low cost of error (food delivery) may set the blocking threshold at 85, whereas a financial organization with strict regulatory requirements will choose a value of 65.

Threshold tuning. Determining the optimal boundaries is a task of balancing two metrics:

• Recall — the share of fraudulent operations detected. The lower the blocking threshold, the more attacks will be stopped.
• Precision — the share of genuinely fraudulent operations among those blocked. The higher the threshold, the fewer false positives and dissatisfied customers.

Shifting the threshold down increases recall but reduces precision: the system begins to reject legitimate operations, generating a flow of support requests. Shifting it up gives the opposite effect — fewer complaints, but higher losses from missed fraud. The right balance is determined by the economics of the specific business: the cost of a single fraud, the costs of manual analysis, and the price of losing a customer due to a false block.

Dynamic adaptation. The behavior of users and the tactics of attackers change constantly. A threshold optimal in January may turn out to be ineffective by March. Therefore, advanced risk scoring APIs support automatic adjustment: the system tracks the share of confirmed fraud in each zone and shifts the boundaries if the metrics deviate from the target values.

Explainability of decisions. Regulatory requirements and internal compliance policies oblige businesses to justify refusals. A risk scoring API must return not only the final value but also a list of the factors that influenced the decision: “the score was raised due to a login from a new device (+12), the use of a VPN (+8), and an atypical transaction amount (+15)”. Such transparency simplifies the analysis of disputed cases, speeds up the training of models on errors, and increases customers’ trust in the system.

Feedback and retraining. Each final decision — confirmed fraud or a false positive — becomes a training example for the model. The faster the outcomes are labeled, the more quickly the system adapts to new attack schemes. Advanced fraud detection APIs make it possible to transmit feedback through a separate endpoint, closing the “event → assessment → decision → labeling → retraining” loop without human involvement.