Transactions API — Screen and Retrieve Transactions

The Transactions API is the core of AntifraudAI. Use it to submit payment transactions for real-time fraud screening and to retrieve the results of previous screenings. Screening is synchronous — the response includes the risk score and decision immediately, with no polling required.

POST /transactions/screen

Submit a transaction for real-time fraud screening. The response includes a risk score (0–100), a decision (allow, review, or block), and an array of the risk signals that contributed to the score.

curl --request POST \
  --url https://api.antifraudai.com/v1/transactions/screen \
  --header 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "user_8821",
    "amount": 349.00,
    "currency": "USD",
    "ip_address": "203.0.113.42",
    "device_fingerprint": "fp_7gHk2mNpQr",
    "payment_method": "card",
    "billing_address": {
      "country": "US",
      "zip": "10001",
      "city": "New York",
      "line1": "123 Main St"
    },
    "metadata": {
      "order_id": "ord_99123",
      "channel": "mobile_app"
    }
  }'

import requests

payload = {
    "user_id": "user_8821",
    "amount": 349.00,
    "currency": "USD",
    "ip_address": "203.0.113.42",
    "device_fingerprint": "fp_7gHk2mNpQr",
    "payment_method": "card",
    "billing_address": {
        "country": "US",
        "zip": "10001",
        "city": "New York",
        "line1": "123 Main St",
    },
    "metadata": {
        "order_id": "ord_99123",
        "channel": "mobile_app",
    },
}

response = requests.post(
    "https://api.antifraudai.com/v1/transactions/screen",
    headers={
        "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json=payload,
)

print(response.json())

const response = await fetch(
  "https://api.antifraudai.com/v1/transactions/screen",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      user_id: "user_8821",
      amount: 349.0,
      currency: "USD",
      ip_address: "203.0.113.42",
      device_fingerprint: "fp_7gHk2mNpQr",
      payment_method: "card",
      billing_address: {
        country: "US",
        zip: "10001",
        city: "New York",
        line1: "123 Main St",
      },
      metadata: {
        order_id: "ord_99123",
        channel: "mobile_app",
      },
    }),
  }
);

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

Request Parameters

string

required

Your internal identifier for the user initiating the transaction. This is used to build the user’s risk profile over time.

number

required

The transaction amount in the currency specified by currency. Must be a positive number (e.g., 349.00).

string

required

ISO 4217 three-letter currency code for the transaction amount (e.g., USD, EUR, GBP).

string

IPv4 or IPv6 address of the user at the time of the transaction. Providing this field significantly improves fraud detection accuracy by enabling geo-velocity and proxy detection signals.

string

Device fingerprint token generated by the AntifraudAI JavaScript SDK. Enables device-level risk signals such as known fraudulent devices and device switching.

string

The payment method used for this transaction. Accepted values: card, bank, wallet, crypto.

object

The billing address associated with the payment method. Providing this enables address verification signals.

Show billing_address fields

string

ISO 3166-1 alpha-2 country code (e.g., US, GB, DE).

string

Postal or ZIP code.

string

City name.

string

First line of the street address.

object

A flat key-value map of custom attributes to attach to this transaction. Use this to pass context such as order IDs, product categories, or channel identifiers. Values must be strings.

Response Fields

string

Unique identifier for this screening result. Use this ID to retrieve the result later via GET /transactions/{id}.

integer

Risk score from 0 (no risk) to 100 (highest risk). Scores are calculated synchronously using AntifraudAI’s ML models and rule engine.

string

The recommended action for this transaction. One of:

allow — low risk; proceed normally
review — elevated risk; a case is automatically created for manual review
block — high risk; decline the transaction

array of strings

List of active risk signals that contributed to the score, e.g. ["velocity_spike", "ip_mismatch", "card_testing_pattern"].

string

ISO 8601 UTC timestamp of when the screening was performed.

Example response:

{
  "transaction_id": "txn_01HXZ9KP3QRMN7B2",
  "risk_score": 72,
  "decision": "review",
  "signals": [
    "velocity_spike",
    "ip_mismatch",
    "high_amount_first_transaction"
  ],
  "created_at": "2024-06-15T10:32:00Z"
}

GET /transactions/

Retrieve the screening result for a previously submitted transaction by its ID.

string

required

The transaction_id returned from the POST /transactions/screen response.

cURL

curl --request GET \
  --url https://api.antifraudai.com/v1/transactions/txn_01HXZ9KP3QRMN7B2 \
  --header 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'

The response contains the same fields as the POST /transactions/screen response.

{
  "transaction_id": "txn_01HXZ9KP3QRMN7B2",
  "risk_score": 72,
  "decision": "review",
  "signals": [
    "velocity_spike",
    "ip_mismatch",
    "high_amount_first_transaction"
  ],
  "created_at": "2024-06-15T10:32:00Z"
}

Screening results are retained for 90 days. Requests for transactions older than 90 days will return a 404 not_found error.

Overview

Endpoints

Transactions API — Screen and Retrieve Transactions

POST /transactions/screen

Request Parameters

Response Fields

GET /transactions/

​POST /transactions/screen

​Request Parameters

​Response Fields

​GET /transactions/

POST /transactions/screen

Request Parameters

Response Fields

GET /transactions/