> ## 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.

# 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.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/assess
openapi: 3.1.0
info:
  title: Clausum API
  version: 1.3.0
  description: >-
    REST API for real-time fraud risk assessment (pay-in and payout), fraud
    reporting, blocklist management, and event ingestion. API version 1.3.0.
    Create Partner API keys (`clm_pub_*`, `clm_sk_*`) in the dashboard under
    Conexiones → Claves API. Webhook ingest uses separate `clm_wh_*` keys
    (Conexiones → Entrada webhooks).
  contact:
    name: Clausum API Support
    email: api@clausum.ai
    url: https://clausum.ai
servers:
  - url: https://sandbox.clausum.ai
    description: Sandbox — integrators and trials
  - url: https://dashboard.clausum.ai
    description: Production dashboard and Partner API
security:
  - apiKeyAuth: []
tags:
  - name: Risk
    description: Real-time risk scoring for pay-in checkout and sessions.
  - name: Payout
    description: Outbound disbursement and treasury transfer assessment.
  - name: Fraud
    description: Report confirmed fraud and trigger the downstream chain.
  - name: Blocklists
    description: Manage dynamic blocklists used during assessment.
  - name: Cases
    description: Manage fraud cases (expedientes) and submit them to regulators.
  - name: Events
    description: Ingest raw events from your payment providers.
  - name: System
    description: Health and status checks.
paths:
  /api/v1/assess:
    post:
      tags:
        - Risk
      summary: Assess transaction risk
      description: >-
        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.
      operationId: assessRisk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssessRequest'
            examples:
              card_payment:
                summary: Card payment with device + behavior signals
                value:
                  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
      responses:
        '200':
          description: Assessment completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessResponse'
              examples:
                approve:
                  summary: Low-risk approval
                  value:
                    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
                decline:
                  summary: Hard block from blocklist
                  value:
                    decision: decline
                    risk_score: 100
                    signals:
                      - blocklist_email
                    signal_details:
                      - code: blocklist_email
                        weight: 100
                        description: 'Email blocked: reported as chargeback'
                    session_id: ps_1716998400000_z9y8x7w6v
                    order_id: ORD-123
                    payment_id: null
                    blocked_by: 'Email blocked: reported as chargeback'
                    latency_ms: 31
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
        - apiKeyAuth: []
components:
  schemas:
    AssessRequest:
      type: object
      required:
        - amount
        - currency
      properties:
        session_id:
          type: string
          description: >-
            Reuse a session id returned by the browser SDK to merge behavioral
            signals.
        order_id:
          type: string
          description: Merchant order / checkout reference.
        payment_id:
          type: string
          description: PSP or payment-ledger charge id (e.g. Stripe pi_*).
        amount:
          type: number
          minimum: 0
          description: >-
            Preferred: decimal major units (e.g. 139.98). Legacy: integer
            without amount_unit interpreted as minor (cents).
        amount_unit:
          type: string
          enum:
            - major
            - minor
          description: Disambiguates integer amounts.
        amount_minor:
          type: number
          description: Explicit amount in minor units (cents).
        currency:
          type: string
          example: MXN
        transaction_type:
          type: string
          example: payment
          description: payment, transfer, withdrawal, etc.
        email:
          type: string
          format: email
        phone:
          type: string
        customer_id:
          type: string
          description: Your internal customer identifier.
        customer_name:
          type: string
        payment_method:
          $ref: '#/components/schemas/PaymentMethod'
        device:
          $ref: '#/components/schemas/Device'
        behavior:
          $ref: '#/components/schemas/Behavior'
        shipping:
          $ref: '#/components/schemas/Address'
        billing:
          $ref: '#/components/schemas/Address'
        metadata:
          type: object
          additionalProperties: true
        submerchant_id:
          type: string
          description: Required for PSP (`organization_type=psp`). Child merchant id.
        submerchant_name:
          type: string
        submerchant:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
    AssessResponse:
      type: object
      properties:
        decision:
          type: string
          enum:
            - approve
            - review
            - challenge
            - decline
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
        signals:
          type: array
          items:
            type: string
          description: Codes of the signals that fired.
        signal_details:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              weight:
                type: integer
              description:
                type: string
        session_id:
          type: string
        order_id:
          type: string
          nullable: true
        payment_id:
          type: string
          nullable: true
        idempotency_key:
          type: string
          nullable: true
        blocked_by:
          type: string
          nullable: true
          description: Reason when the transaction was hard-blocked.
        latency_ms:
          type: integer
        assess_flow:
          type: string
          enum:
            - payin
            - payout
        flow:
          type: string
          description: Present on payout assess responses.
          example: payout
        field_warnings:
          type: object
          description: >-
            Present when recommended segment fields were omitted; assess still
            succeeds.
          properties:
            missing_recommended:
              type: array
              items:
                type: string
            organization_segment:
              type: string
              enum:
                - merchant
                - psp
                - bank
                - other
            field_requirements_doc:
              type: string
    PaymentMethod:
      type: object
      properties:
        type:
          type: string
          example: card
          description: card, bank, wallet, crypto, etc.
        card_bin:
          type: string
          description: First 6 digits.
        card_last4:
          type: string
        card_country:
          type: string
        card_brand:
          type: string
        bank_code:
          type: string
        wallet_type:
          type: string
    Device:
      type: object
      properties:
        fingerprint:
          type: string
        user_agent:
          type: string
        ip:
          type: string
        language:
          type: string
        timezone:
          type: string
        screen_resolution:
          type: string
    Behavior:
      type: object
      properties:
        session_duration_ms:
          type: integer
        mouse_movements:
          type: integer
        key_presses:
          type: integer
        scroll_events:
          type: integer
        focus_changes:
          type: integer
        copy_paste_events:
          type: integer
        form_fill_time_ms:
          type: integer
    Address:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        postal_code:
          type: string
    ApiError:
      type: object
      properties:
        error:
          oneOf:
            - type: string
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type: object
                  additionalProperties: true
  responses:
    ValidationError:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ServiceUnavailable:
      description: Assess maintenance mode
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: ASSESS_MAINTENANCE
              message: Assess temporarily unavailable
    GatewayTimeout:
      description: Assess timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: ASSESS_TIMEOUT
              message: Assess timed out — retry with same idempotency key
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Partner secret or publishable key, e.g. `clm_sk_...` or `clm_pub_...`
        (assess only).
      x-default: clm_sk_your_secret_key

````