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

# Risk Session

> Initialize a risk evaluation session token for use with the Risk Score endpoint.



## OpenAPI

````yaml specs/ingopay-risk.yaml POST /risk/risksession/v2
openapi: 3.0.3
info:
  title: IngoPay API — Risk (RiskSession + RiskScore)
  description: >
    The IngoPay Risk API provides two endpoints used together to assess
    transaction risk prior to initiating a pull (debit) payment.


    **Typical flow:**

    1. Call `POST /risk/risksession/v2` to initialize a risk session and
       obtain a `risk_session_token`.

    2. Integrate the Sardine device fingerprinting and behavioral data
       collection SDK on the client side using the `risk_session_token`
       to associate the session.

    3. Call `POST /risk/riskscore/v2` with the transaction data and
       `risk_session_token` to receive a risk score and a
       `risk_assessment_token`.

    4. Pass the `risk_assessment_token` into the subsequent debit process
       request (`/gateway/v12/debit/process`) via
       `transaction.risk_assessment_token`.


    **Risk Score Range:**

    | Score Range | Description | |---|---| | 2 – 299 | Discrete scores
    indicating some degree of high risk / fraud | | 300 – 3000 | Continuous
    scores correlating to discerned risk — 3000 is best |


    > **Prerequisites:** Usage of the IngoPay Risk API requires integration of
    third-party artifacts for device fingerprinting and behavioral data
    collection. SDK artifacts and packages will be provided by your assigned
    Integration Manager.


    > **Account type scope:** `account_type` for RiskScore is restricted to `CA`
    (card) and `AC` (ACH) only.


    > **Conditional objects:** `transaction_ifa{}` is required when the client
    is configured with Identity Fraud Assessment (`ifa_enabled` flag).
    `transaction_open_banking{}` is conditional based on client configuration.
    Contact your Ingo integration manager to confirm which objects apply to your
    integration.
  version: '2'
  contact:
    name: Ingo Money Developer Support
    url: https://developers.ingomoney.com
servers:
  - url: https://payapi-sandbox.ingo.money
    description: Sandbox
  - url: https://payapi.ingo.money
    description: Production
security:
  - HmacAuth: []
paths:
  /risk/risksession/v2:
    post:
      tags:
        - Risk
      summary: Initialize a risk session
      description: >
        Initiates a risk session with Ingo Payments. Returns a
        `risk_session_token` that must be passed to the Sardine device
        fingerprinting SDK and subsequently to the RiskScore endpoint.
      operationId: riskSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskSessionRequest'
            example:
              request:
                participant_id: '12345'
                timestamp: '1721337425'
      responses:
        '200':
          description: Risk session initialized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskSessionResponse'
              example:
                request:
                  participant_id: '12345'
                  timestamp: '1721413825'
                response:
                  status: '100'
                  message: Success
                  duration: '0.30398297309875'
                session:
                  risk_session_token: 1e97dde1-f10f-4caf-8726-da6fc207ecb8
        '400':
          description: Validation error or unrecognized participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                request:
                  participant_id: '12345'
                  timestamp: '1721413825'
                response:
                  status: '800'
                  message: Unknown Client
components:
  schemas:
    RiskSessionRequest:
      type: object
      required:
        - request
      properties:
        request:
          type: object
          required:
            - participant_id
            - timestamp
          description: General information associated with the API request.
          properties:
            participant_id:
              type: string
              maxLength: 5
              description: Unique participant identifier assigned by Ingo.
              example: '12345'
            timestamp:
              type: string
              maxLength: 32
              description: Unix timestamp of the request.
              example: '1721337425'
    RiskSessionResponse:
      type: object
      properties:
        request:
          type: object
          properties:
            participant_id:
              type: string
              example: '12345'
            timestamp:
              type: string
              example: '1721413825'
        response:
          type: object
          properties:
            status:
              type: string
              description: >
                Numeric code describing the status of the API request. 100 =
                Success.
              example: '100'
            message:
              type: string
              description: Text description associated with the status code.
              example: Success
            duration:
              type: string
              description: Time in seconds to complete the request.
              example: '0.30398297309875'
        session:
          type: object
          description: >
            Identifiers to be embedded in client-side web/mobile code in support
            of device fingerprinting and behavioral data collection.
          properties:
            risk_session_token:
              type: string
              description: >
                Ingo-assigned session ID (UUID). Pass this value to the Sardine
                device fingerprinting SDK and subsequently to the
                `transaction.risk_session_token` field of the RiskScore request.
                Default session expiry is 30 minutes.
              example: 1e97dde1-f10f-4caf-8726-da6fc207ecb8
    ErrorResponse:
      type: object
      properties:
        request:
          type: object
          properties:
            participant_id:
              type: string
              example: '12345'
            timestamp:
              type: string
              example: '1721337427'
        response:
          type: object
          properties:
            status:
              type: string
              example: '400'
            message:
              type: string
              example: Validation Error
  securitySchemes:
    HmacAuth:
      type: http
      scheme: hmac-sha512
      description: >-
        HMAC-SHA512 signed Authorization header. See the Authentication page for
        the complete signing guide.

````