The Verdikt API

Introduction

The Verdikt API is organised around REST. It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes. Every request is scored in real time by our AI decisioning engine: a transaction foundation model, a graph network and risk models running in parallel.

Authentication

Authenticate with your secret API key in the Authorization header as a bearer token. Keys are environment-scoped: test keys are prefixed vk_test_ and live keys vk_live_. Live keys are billable and eligible for the chargeback guarantee; test keys always run in sandbox. Never expose a live secret key in client-side code.

Sandbox scoring is deterministic. Use the reserved emails [email protected], [email protected] and [email protected] to force each verdict while integrating.

Making requests

All requests must be made over HTTPS and send a JSON body with Content-Type: application/json. The API recognises these headers:

Every response includes X-Request-Id, X-RateLimit-Limit and X-RateLimit-Remaining headers.

Idempotency

To safely retry requests without accidentally scoring the same order twice, pass a unique Idempotency-Key header (your order_id is a good choice). The first request is processed and the result stored against the key; subsequent requests with the same key return the original decision without re-scoring. Keys are retained for 24 hours.

The Decision object

A decision represents a single risk evaluation. These are the fields it returns:

Create a decision

Submit a transaction and receive a real-time verdict. Request body fields:

Request

curl https://verdiktt.com/api/v1/decisions \
  -H "Authorization: Bearer vk_live_4f9c20a1d8e3" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_8842" \
  -d '{
    "order_id": "ord_8842",
    "amount": 249.00,
    "currency": "USD",
    "product_type": "physical",
    "customer": {
      "email": "[email protected]",
      "ip": "81.2.69.142",
      "device_id": "dvc_a91f"
    }
  }'

Response

{
  "id": "dec_9f3a21c7c4e0",
  "object": "decision",
  "created": 1781827200,
  "livemode": true,
  "order_id": "ord_8842",
  "amount": 249.0,
  "currency": "USD",
  "product_type": "physical",
  "verdict": "approve",
  "score": 0.07,
  "guaranteed": true,
  "reasons": [
    "email_reputation_ok",
    "established_device",
    "shipping_billing_match",
    "graph_no_fraud_link"
  ],
  "latency_ms": 43
}

Retrieve a decision

Fetch a previously created decision by its id.

curl https://verdiktt.com/api/v1/decisions/dec_9f3a21c7c4e0 \
  -H "Authorization: Bearer vk_live_4f9c20a1d8e3"

List decisions

Returns a list of decisions, most recent first. Accepts an optional limit query parameter (default 10, max 100).

curl "https://verdiktt.com/api/v1/decisions?limit=10" \
  -H "Authorization: Bearer vk_live_4f9c20a1d8e3"

Response

{
  "object": "list",
  "url": "/v1/decisions",
  "has_more": false,
  "data": [
    { "id": "dec_9f3a21c7c4e0", "verdict": "approve", "score": 0.07, "...": "..." },
    { "id": "dec_61b0a4e2f199", "verdict": "review",  "score": 0.54, "...": "..." }
  ]
}

Live playground

Send a real request to the sandbox engine running in this environment. Edit the body or pick a preset, then send. Try the reserved test emails to force each verdict, or a disposable-email domain to watch the score climb.

// Click “Send request” to score this transaction
// against the live sandbox engine.

Verdicts & scores

The score is a calibrated fraud probability. The verdict applies your configured thresholds (defaults shown):

Errors

Verdikt uses conventional HTTP status codes and returns a machine-readable error object.

{
  "error": {
    "type": "invalid_request_error",
    "message": "customer.email is required.",
    "fields": ["customer.email is required."]
  }
}

Rate limits

Production accounts are limited to 1,000 req/s by default, burstable on request. When you exceed the limit the API returns 429. Inspect X-RateLimit-Remaining and implement exponential backoff. Decisioning calls are designed to fail fast, so a safe default is to fail open (approve) or closed (review) per your risk appetite if a call times out.

Webhooks

Verdikt sends signed webhook events when an asynchronous outcome occurs: a held order resolves, a guarantee is confirmed, or a chargeback is reported by the network. Verify the Verdikt-Signature header against your endpoint secret.

{
  "id": "evt_2c8f10a4",
  "type": "chargeback.received",
  "created": 1781913600,
  "data": {
    "decision_id": "dec_9f3a21c7c4e0",
    "order_id": "ord_8842",
    "amount": 249.0,
    "currency": "USD",
    "reason_code": "10.4",
    "guaranteed": true
  }
}

Libraries

Official, typed SDKs wrap the REST API for every major stack: