Risk

Assess transaction risk

Scores a transaction or session in real time and returns a decision (approve, review, challenge, or decline). Call this before you capture a payment or complete a sensitive action. Authenticate with a secret API key (clm_sk_...); a publishable key (clm_pub_...) may be used from the browser SDK.

Field requirements by organization segment (comercio, psp, banco): always amount + currency; PSP requires explicit submerchant_id; merchant recommends order_id, device.ip (server), payer identity. See GET /api/v1/assess → field_requirements_by_segment and docs MERCHANT_INTEGRATION.md#assess-fields-by-segment. Missing recommended fields may appear in field_warnings without failing the request.

Payment gateways: Clausum does not POST decisions to Stripe or other PSPs. Your backend calls assess, then your backend calls the PSP capture API.

POST

api

assess

Assess transaction risk

curl --request POST \
  --url https://sandbox.clausum.ai/api/v1/assess \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1500,
  "currency": "MXN",
  "transaction_type": "payment",
  "email": "customer@example.com",
  "customer_id": "cus_abc123",
  "payment_method": {
    "type": "card",
    "card_bin": "411111",
    "card_last4": "4242",
    "card_country": "MX",
    "card_brand": "visa"
  },
  "device": {
    "fingerprint": "fp_9a8b7c6d",
    "ip": "201.150.10.22",
    "user_agent": "Mozilla/5.0"
  },
  "billing": {
    "country": "MX",
    "city": "CDMX",
    "postal_code": "06600"
  },
  "order_id": "ORD-123",
  "payment_id": "pi_3Nxyz"
}
'

import requests

url = "https://sandbox.clausum.ai/api/v1/assess"

payload = {
    "amount": 1500,
    "currency": "MXN",
    "transaction_type": "payment",
    "email": "customer@example.com",
    "customer_id": "cus_abc123",
    "payment_method": {
        "type": "card",
        "card_bin": "411111",
        "card_last4": "4242",
        "card_country": "MX",
        "card_brand": "visa"
    },
    "device": {
        "fingerprint": "fp_9a8b7c6d",
        "ip": "201.150.10.22",
        "user_agent": "Mozilla/5.0"
    },
    "billing": {
        "country": "MX",
        "city": "CDMX",
        "postal_code": "06600"
    },
    "order_id": "ORD-123",
    "payment_id": "pi_3Nxyz"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 1500,
    currency: 'MXN',
    transaction_type: 'payment',
    email: 'customer@example.com',
    customer_id: 'cus_abc123',
    payment_method: {
      type: 'card',
      card_bin: '411111',
      card_last4: '4242',
      card_country: 'MX',
      card_brand: 'visa'
    },
    device: {fingerprint: 'fp_9a8b7c6d', ip: '201.150.10.22', user_agent: 'Mozilla/5.0'},
    billing: {country: 'MX', city: 'CDMX', postal_code: '06600'},
    order_id: 'ORD-123',
    payment_id: 'pi_3Nxyz'
  })
};

fetch('https://sandbox.clausum.ai/api/v1/assess', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.clausum.ai/api/v1/assess",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 1500,
    'currency' => 'MXN',
    'transaction_type' => 'payment',
    'email' => 'customer@example.com',
    'customer_id' => 'cus_abc123',
    'payment_method' => [
        'type' => 'card',
        'card_bin' => '411111',
        'card_last4' => '4242',
        'card_country' => 'MX',
        'card_brand' => 'visa'
    ],
    'device' => [
        'fingerprint' => 'fp_9a8b7c6d',
        'ip' => '201.150.10.22',
        'user_agent' => 'Mozilla/5.0'
    ],
    'billing' => [
        'country' => 'MX',
        'city' => 'CDMX',
        'postal_code' => '06600'
    ],
    'order_id' => 'ORD-123',
    'payment_id' => 'pi_3Nxyz'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.clausum.ai/api/v1/assess"

	payload := strings.NewReader("{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.clausum.ai/api/v1/assess")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.clausum.ai/api/v1/assess")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}"

response = http.request(request)
puts response.read_body

{
  "decision": "approve",
  "risk_score": 8,
  "signals": [
    "short_session"
  ],
  "signal_details": [
    {
      "code": "short_session",
      "weight": 8,
      "description": "Session under 5s"
    }
  ],
  "session_id": "ps_1716998400000_a1b2c3d4e",
  "order_id": "ORD-123",
  "payment_id": "pi_3Nxyz",
  "blocked_by": null,
  "latency_ms": 42
}

Authorizations

Authorization

string

header

default:clm_sk_your_secret_key

required

Partner secret or publishable key, e.g. clm_sk_... or clm_pub_... (assess only).

Body

application/json

amount

number

required

Preferred: decimal major units (e.g. 139.98). Legacy: integer without amount_unit interpreted as minor (cents).

Required range: x >= 0

currency

string

required

Example:

"MXN"

session_id

string

Reuse a session id returned by the browser SDK to merge behavioral signals.

order_id

string

Merchant order / checkout reference.

payment_id

string

PSP or payment-ledger charge id (e.g. Stripe pi_*).

amount_unit

enum<string>

Disambiguates integer amounts.

Available options:

major,

minor

amount_minor

number

Explicit amount in minor units (cents).

transaction_type

string

payment, transfer, withdrawal, etc.

Example:

"payment"

string<email>

phone

string

customer_id

string

Your internal customer identifier.

customer_name

string

payment_method

object

Show child attributes

device

object

Show child attributes

behavior

object

Show child attributes

shipping

object

Show child attributes

billing

object

Show child attributes

metadata

object

submerchant_id

string

Required for PSP (organization_type=psp). Child merchant id.

submerchant_name

string

submerchant

object

Show child attributes

Response

Assessment completed

decision

enum<string>

Available options:

approve,

review,

challenge,

decline

risk_score

integer

Required range: 0 <= x <= 100

signals

string[]

Codes of the signals that fired.

signal_details

object[]

Show child attributes

session_id

string

order_id

string | null

payment_id

string | null

idempotency_key

string | null

blocked_by

string | null

Reason when the transaction was hard-blocked.

latency_ms

integer

assess_flow

enum<string>

Available options:

payin,

payout

flow

string

Present on payout assess responses.

Example:

"payout"

field_warnings

object

Present when recommended segment fields were omitted; assess still succeeds.

Show child attributes

Assess API catalog (payout)Payout field requirements and amount rules. No authentication required.

Assess transaction risk

curl --request POST \
  --url https://sandbox.clausum.ai/api/v1/assess \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1500,
  "currency": "MXN",
  "transaction_type": "payment",
  "email": "customer@example.com",
  "customer_id": "cus_abc123",
  "payment_method": {
    "type": "card",
    "card_bin": "411111",
    "card_last4": "4242",
    "card_country": "MX",
    "card_brand": "visa"
  },
  "device": {
    "fingerprint": "fp_9a8b7c6d",
    "ip": "201.150.10.22",
    "user_agent": "Mozilla/5.0"
  },
  "billing": {
    "country": "MX",
    "city": "CDMX",
    "postal_code": "06600"
  },
  "order_id": "ORD-123",
  "payment_id": "pi_3Nxyz"
}
'

import requests

url = "https://sandbox.clausum.ai/api/v1/assess"

payload = {
    "amount": 1500,
    "currency": "MXN",
    "transaction_type": "payment",
    "email": "customer@example.com",
    "customer_id": "cus_abc123",
    "payment_method": {
        "type": "card",
        "card_bin": "411111",
        "card_last4": "4242",
        "card_country": "MX",
        "card_brand": "visa"
    },
    "device": {
        "fingerprint": "fp_9a8b7c6d",
        "ip": "201.150.10.22",
        "user_agent": "Mozilla/5.0"
    },
    "billing": {
        "country": "MX",
        "city": "CDMX",
        "postal_code": "06600"
    },
    "order_id": "ORD-123",
    "payment_id": "pi_3Nxyz"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 1500,
    currency: 'MXN',
    transaction_type: 'payment',
    email: 'customer@example.com',
    customer_id: 'cus_abc123',
    payment_method: {
      type: 'card',
      card_bin: '411111',
      card_last4: '4242',
      card_country: 'MX',
      card_brand: 'visa'
    },
    device: {fingerprint: 'fp_9a8b7c6d', ip: '201.150.10.22', user_agent: 'Mozilla/5.0'},
    billing: {country: 'MX', city: 'CDMX', postal_code: '06600'},
    order_id: 'ORD-123',
    payment_id: 'pi_3Nxyz'
  })
};

fetch('https://sandbox.clausum.ai/api/v1/assess', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.clausum.ai/api/v1/assess",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 1500,
    'currency' => 'MXN',
    'transaction_type' => 'payment',
    'email' => 'customer@example.com',
    'customer_id' => 'cus_abc123',
    'payment_method' => [
        'type' => 'card',
        'card_bin' => '411111',
        'card_last4' => '4242',
        'card_country' => 'MX',
        'card_brand' => 'visa'
    ],
    'device' => [
        'fingerprint' => 'fp_9a8b7c6d',
        'ip' => '201.150.10.22',
        'user_agent' => 'Mozilla/5.0'
    ],
    'billing' => [
        'country' => 'MX',
        'city' => 'CDMX',
        'postal_code' => '06600'
    ],
    'order_id' => 'ORD-123',
    'payment_id' => 'pi_3Nxyz'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.clausum.ai/api/v1/assess"

	payload := strings.NewReader("{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.clausum.ai/api/v1/assess")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.clausum.ai/api/v1/assess")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1500,\n  \"currency\": \"MXN\",\n  \"transaction_type\": \"payment\",\n  \"email\": \"customer@example.com\",\n  \"customer_id\": \"cus_abc123\",\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card_bin\": \"411111\",\n    \"card_last4\": \"4242\",\n    \"card_country\": \"MX\",\n    \"card_brand\": \"visa\"\n  },\n  \"device\": {\n    \"fingerprint\": \"fp_9a8b7c6d\",\n    \"ip\": \"201.150.10.22\",\n    \"user_agent\": \"Mozilla/5.0\"\n  },\n  \"billing\": {\n    \"country\": \"MX\",\n    \"city\": \"CDMX\",\n    \"postal_code\": \"06600\"\n  },\n  \"order_id\": \"ORD-123\",\n  \"payment_id\": \"pi_3Nxyz\"\n}"

response = http.request(request)
puts response.read_body

{
  "decision": "approve",
  "risk_score": 8,
  "signals": [
    "short_session"
  ],
  "signal_details": [
    {
      "code": "short_session",
      "weight": 8,
      "description": "Session under 5s"
    }
  ],
  "session_id": "ps_1716998400000_a1b2c3d4e",
  "order_id": "ORD-123",
  "payment_id": "pi_3Nxyz",
  "blocked_by": null,
  "latency_ms": 42
}

Overview

Endpoints

Assess transaction risk

Authorizations

Body

Response