> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time assessment (pay-in)

> POST /api/v1/assess — evaluate checkout risk before capture

Pay-in assess is the **primary** integration: call Clausum when the customer submits payment, then branch on `decision` before charging the card or wallet.

## Endpoint

```
POST https://dashboard.clausum.ai/api/v1/assess
Authorization: Bearer clm_sk_...
Content-Type: application/json
Idempotency-Key: <optional header; order_id also dedupes>
```

Partner permission required: **Assess** on the API key.

## Request body

```json theme={null}
{
  "amount": 125.00,
  "amount_unit": "major",
  "currency": "USD",
  "order_id": "shop_order_8842",
  "submerchant_id": "sm_optional_psp_only",
  "customer": {
    "email": "buyer@example.com",
    "phone": "+15551234567",
    "ip_address": "198.51.100.42",
    "billing_country": "US"
  },
  "device": {
    "fingerprint": "fp_abc123",
    "user_agent": "Mozilla/5.0 ..."
  },
  "payment_method": {
    "type": "card",
    "bin": "424242",
    "last4": "4242"
  },
  "metadata": {
    "cart_id": "cart_99"
  }
}
```

### Amounts

The assess API accepts flexible amount encoding. **Preferred:** decimal major units.

| Field          | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `amount`       | Decimal major (e.g. `125.00` USD) — **recommended**                                    |
| `amount_unit`  | `"major"` or `"minor"` — disambiguates integers                                        |
| `amount_minor` | Explicit cents (always minor units)                                                    |
| Legacy         | Integer without `amount_unit` → interpreted as **cents** (deprecation header returned) |

| Context                                      | Unit                         |
| -------------------------------------------- | ---------------------------- |
| Dashboard simulation UI                      | Major units (125 = \$125.00) |
| Blocklist / rule `amount_limit` in Dashboard | Major units                  |

Call `GET /api/v1/assess` (no auth) for the live amount and field-requirements catalog for your deployment version.

### Idempotency

* Send stable **`order_id`** per checkout attempt
* Retries with the same `order_id` return the **cached** decision (no double scoring)
* Optional header `Idempotency-Key` for partners that prefer header-based dedup

### PSP submerchants

If your organization type is **PSP**, pass `submerchant_id` (Clausum UUID from [Submerchants API](/guides/psp-submerchants)) so rules and blocklists scope to that merchant.

## Response

```json theme={null}
{
  "decision": "approve",
  "risk_score": 18,
  "signals": ["velocity_email_1h"],
  "session_id": "ps_7f3a...",
  "assess_flow": "payin",
  "protection_scope": {
    "rules_org_id": "uuid",
    "active_rules": 12,
    "active_blocklists": 3
  }
}
```

### Decisions

| Decision    | Recommended action                                                           |
| ----------- | ---------------------------------------------------------------------------- |
| `approve`   | Proceed with capture                                                         |
| `review`    | Hold for manual review or step-up                                            |
| `challenge` | SCA / OTP / additional verification                                          |
| `decline`   | Do not capture; show generic failure. Triggers `transaction.blocked` webhook |

## Health and resilience

| HTTP                         | Meaning                                         |
| ---------------------------- | ----------------------------------------------- |
| `200`                        | Decision returned                               |
| `503` + `ASSESS_MAINTENANCE` | Platform maintenance — use your fallback policy |
| `504` + `ASSESS_TIMEOUT`     | Timeout — retry with same `order_id`            |

See [Assess resilience](/guides/assess-resilience).

## Simulation (dashboard)

Authenticated users can test via `POST /api/v1/simulation/assess` (same payload shape, tagged as simulation). Do **not** use `/api/demo/assess` for your tenant — that endpoint targets the public demo org.

## Related

* [Payout assess](/guides/payout-assessment) — outbound flows
* [Webhook events](/concepts/webhook-events) — `transaction.created` on approve/review/challenge
* [Blocklists](/concepts/blocklists) — tenant and platform lists