Screen a Transaction for Fraud with AntifraudAI API

Every payment or user-initiated event in your system can be screened against AntifraudAI’s ML engine before it’s processed. Within milliseconds, AntifraudAI returns a risk score (0–100) and a decision — allow, review, or block — so your application can act immediately. This guide walks you through the full flow from building a request to handling each outcome.

Prepare your transaction data

Gather the following fields before calling the API. Richer input data leads to more accurate scoring — include as many fields as your stack can provide.

Field	Type	Required	Description
`user_id`	string	✅	Your internal identifier for the user
`amount`	number	✅	Transaction amount (decimal)
`currency`	string	✅	ISO 4217 currency code (e.g. `USD`, `EUR`)
`ip_address`	string	✅	IPv4 or IPv6 address of the request origin
`device_fingerprint`	string	✗	Unique token identifying the user’s device
`payment_method`	string	✅	One of `card`, `bank`, or `wallet`
`billing_address`	object	✗	Object containing `country` (ISO 3166-1 alpha-2) and `zip`

The device_fingerprint field is optional but strongly recommended. Transactions submitted without it cannot benefit from device-based velocity and anomaly signals.

Call POST /transactions/screen

Submit the transaction payload to the screening endpoint. Use your live API key for production traffic and your sandbox key for testing.

curl -X POST https://api.antifraudai.com/v1/transactions/screen \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "amount": 499.99,
    "currency": "USD",
    "ip_address": "203.0.113.5",
    "payment_method": "card",
    "billing_address": {
      "country": "US",
      "zip": "10001"
    }
  }'

import requests

url = "https://api.antifraudai.com/v1/transactions/screen"
headers = {
    "Authorization": "Bearer sk_live_xxxx",
    "Content-Type": "application/json",
}
payload = {
    "user_id": "usr_abc123",
    "amount": 499.99,
    "currency": "USD",
    "ip_address": "203.0.113.5",
    "payment_method": "card",
    "billing_address": {
        "country": "US",
        "zip": "10001",
    },
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()
print(result)

const response = await fetch(
  "https://api.antifraudai.com/v1/transactions/screen",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      user_id: "usr_abc123",
      amount: 499.99,
      currency: "USD",
      ip_address: "203.0.113.5",
      payment_method: "card",
      billing_address: {
        country: "US",
        zip: "10001",
      },
    }),
  }
);

const result = await response.json();
console.log(result);

Handle the response

A successful screening returns HTTP 200 with the following JSON body:

{
  "transaction_id": "txn_9f8e7d6c",
  "risk_score": 68,
  "decision": "review",
  "signals": ["new_device", "high_velocity"],
  "created_at": "2024-03-15T10:23:45Z"
}

Field	Description
`transaction_id`	Unique AntifraudAI identifier — store this for later lookups
`risk_score`	Integer from 0 (no risk) to 100 (highest risk)
`decision`	`allow`, `review`, or `block`
`signals`	Array of human-readable strings explaining the scoring
`created_at`	ISO 8601 timestamp of when the screening completed

Act on the decision

Branch your application logic on the decision field returned in the response.

allow
review
block

The transaction passed screening. Proceed normally — complete the payment, fulfil the order, or grant access.

Python

if result["decision"] == "allow":
    process_payment(result["transaction_id"])

The transaction is suspicious but not conclusive. Hold the transaction and wait for a human agent to resolve the case.AntifraudAI automatically creates a Case for every review decision. You can monitor cases in the dashboard or via the Cases API.

Python

if result["decision"] == "review":
    hold_transaction(result["transaction_id"])
    notify_review_team(result["transaction_id"])

The transaction is high-risk. Decline it immediately and surface an appropriate error to the user (e.g. “We were unable to process this payment”).

Python

if result["decision"] == "block":
    return {"error": "Transaction declined. Please contact support."}

Never reveal the specific fraud signals to the end user — this information can be used to craft bypass attempts.

Retrieve transaction details later

You can fetch the full details of any previously screened transaction using its transaction_id.

curl https://api.antifraudai.com/v1/transactions/txn_9f8e7d6c \
  -H "Authorization: Bearer sk_live_xxxx"

response = requests.get(
    "https://api.antifraudai.com/v1/transactions/txn_9f8e7d6c",
    headers={"Authorization": "Bearer sk_live_xxxx"},
)
print(response.json())

Decisions returned at screening time are final for that transaction record. To change an outcome — for example, to approve a transaction that was flagged for review — use the Cases API to resolve the associated case. Resolving a case does not retroactively alter the original decision field but does update the case status and can trigger downstream webhooks.

Manage Cases

Review and resolve fraud cases that are created when a transaction decision is review.

Risk Scoring

Understand how AntifraudAI calculates risk scores and what each signal means.

Get Started

Core Concepts

Guides

Configuration

Help

Screen a Transaction for Fraud with AntifraudAI API

Manage Cases

Risk Scoring

​Related guides

Manage Cases

Risk Scoring

Related guides