Incognia Transactions API

openapi: 3.2.0
info:
  title: Incognia Transactions API
  version: v2
  description: Incognia is a location identity and device fingerprinting platform for fraud prevention.
  contact:
    name: Incognia Developer Support
    url: https://developer.incognia.com/
  x-source: Faithfully reconstructed from the official Incognia Go client library (github.com/inloco/incognia-go) endpoints, request and response types. Not a provider-published OpenAPI.
servers:
- url: https://api.incognia.com/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Transactions
  description: Login and payment risk assessment
paths:
  /v2/authentication/transactions:
    post:
      operationId: registerTransaction
      tags:
      - Transactions
      summary: Register a login or payment transaction for risk assessment
      description: Evaluate a login or payment transaction and return a risk assessment. Set type to "login" or "payment". Payment transactions may include payment_value, payment_methods and addresses; both accept an account_id to bind the assessment to a known user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '200':
          description: Transaction risk assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionAssessment'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access token lacks permission for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    StructuredAddress:
      type: object
      properties:
        locale:
          type: string
        country_name:
          type: string
        country_code:
          type: string
        state:
          type: string
        city:
          type: string
        county:
          type: string
        borough:
          type: string
        neighborhood:
          type: string
        street:
          type: string
        number:
          type: string
        complements:
          type: string
        postal_code:
          type: string
    TransactionAddress:
      type: object
      properties:
        type:
          type: string
          enum:
          - shipping
          - billing
          - home
        address_coordinates:
          $ref: '#/components/schemas/Coordinates'
        structured_address:
          $ref: '#/components/schemas/StructuredAddress'
        address_line:
          type: string
    TransactionAssessment:
      type: object
      properties:
        id:
          type: string
        risk_assessment:
          $ref: '#/components/schemas/RiskAssessment'
        device_id:
          type: string
        evidence:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        actions:
          type: array
          items:
            type: string
        signals:
          type: object
          additionalProperties: true
    Coordinates:
      type: object
      properties:
        lat:
          type: number
          format: double
        lng:
          type: number
          format: double
    Error:
      type: object
      description: Incognia error envelope.
      properties:
        message:
          type: string
          example: missing credentials
    PersonID:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
    RiskAssessment:
      type: string
      enum:
      - low_risk
      - high_risk
      - unknown_risk
      description: Overall risk verdict returned by Incognia.
    Location:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        collected_at:
          type: string
          format: date-time
    CardInfo:
      type: object
      properties:
        bin:
          type: string
        last_four_digits:
          type: string
        expiry_year:
          type: string
        expiry_month:
          type: string
    Reason:
      type: object
      properties:
        code:
          type: string
        source:
          type: string
    PaymentValue:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
    PaymentMethod:
      type: object
      properties:
        identifier:
          type: string
        type:
          type: string
          enum:
          - account_balance
          - apple_pay
          - bancolombia
          - boleto_bancario
          - cash
          - credit_card
          - credit_card_pos
          - debit_card
          - google_pay
          - meal_voucher
          - nu_pay
          - paypal
          - pix
          - pix_refund
          - tef
          - ted
        credit_card_info:
          $ref: '#/components/schemas/CardInfo'
        debit_card_info:
          $ref: '#/components/schemas/CardInfo'
        brand:
          type: string
    TransactionRequest:
      type: object
      required:
      - type
      - account_id
      properties:
        type:
          type: string
          enum:
          - login
          - payment
        account_id:
          type: string
        external_id:
          type: string
        tenant_id:
          type: string
        policy_id:
          type: string
        app_version:
          type: string
        device_os:
          type: string
        installation_id:
          type: string
        session_token:
          type: string
        request_token:
          type: string
        related_web_request_token:
          type: string
        store_id:
          type: string
        payment_method_identifier:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/TransactionAddress'
        payment_value:
          $ref: '#/components/schemas/PaymentValue'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
        custom_properties:
          type: object
          additionalProperties: true
        person_id:
          $ref: '#/components/schemas/PersonID'
        countries:
          type: array
          items:
            type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: client_id and client_secret sent as HTTP Basic credentials to the token endpoint.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer access token obtained from POST /v2/token.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client-credentials grant. No scopes are defined; access is scoped by the credential's tenant.
      flows:
        clientCredentials:
          tokenUrl: https://api.incognia.com/api/v2/token
          scopes: {}