Forter Disputes API

openapi: 3.0.3
info:
  title: Forter Accounts Disputes API
  description: 'Forter is a fraud prevention and digital identity platform for online commerce. Its Core API returns real-time trust decisions for orders, payments, account signups, and logins, and supports chargeback recovery, abuse prevention, and data-privacy workflows.


    GROUNDING NOTE: The paths, HTTP methods, and authentication scheme in this document are grounded in Forter''s public documentation at docs.forter.com (see each operation''s `x-forter-status`). Request and response BODY schemas are MODELED for orientation - Forter does not publish a machine-readable OpenAPI, and the full order/account payloads are large and provisioned per-integration. Treat the schemas below as representative, not authoritative; confirm exact fields against your account''s customized API reference in the Forter Portal.


    ACCESS: Forter is enterprise / contact-sales. Credentials (a per-account site ID and an API key) are provisioned by Forter during onboarding. Requests are sent to a dedicated per-tenant host by prepending your site ID to the API host - `https://{siteId}.api.forter.secure.com/{endpoint}`. The generic host `api.forter.secure.com` shown in the servers block is the documented form; the bare host does not resolve without the site-ID prefix.'
  version: '1.0'
  contact:
    name: Forter
    url: https://www.forter.com
servers:
- url: https://api.forter.secure.com
  description: 'Documented API host. In practice, prepend your account site ID: https://{siteId}.api.forter.secure.com'
security:
- basicAuth: []
tags:
- name: Disputes
  description: Chargeback disputes and customer compensation requests.
paths:
  /v2/unified/compensation/request/{id}:
    parameters:
    - $ref: '#/components/parameters/GenericId'
    post:
      operationId: submitCompensationRequest
      tags:
      - Disputes
      summary: Submit a compensation request for a decision
      description: Send information about a customer-initiated request for compensation (such as a refund or reship) to receive a fraud or abuse decision. Can be submitted at the order level or the item level.
      x-forter-status: Path/method confirmed against docs.forter.com (Compensation request). Request/response schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompensationInput'
      responses:
        '200':
          description: A Forter decision for the compensation request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/dispute/{id}:
    parameters:
    - $ref: '#/components/parameters/GenericId'
    post:
      operationId: submitDispute
      tags:
      - Disputes
      summary: Report a dispute (chargeback)
      description: Inform Forter of a dispute initiated by a customer, for any dispute not already reported via a payment-processor webhook. No decision is returned; the input improves the model and enables chargeback recovery.
      x-forter-status: MODELED PATH. The Disputes group is documented at docs.forter.com, but the exact path/version was not verified from a public code sample. Confirm against your account's API reference. Request schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeInput'
      responses:
        '200':
          description: Acknowledgement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ack'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    GenericId:
      name: id
      in: path
      required: true
      description: A unique identifier for the resource / event.
      schema:
        type: string
  schemas:
    DisputeInput:
      type: object
      description: MODELED dispute (chargeback) payload.
      properties:
        orderId:
          type: string
        disputeType:
          type: string
        disputeTime:
          type: integer
        amount:
          $ref: '#/components/schemas/Amount'
        reason:
          type: string
    Ack:
      type: object
      description: MODELED acknowledgement envelope.
      properties:
        status:
          type: string
          example: success
    Decision:
      type: object
      description: MODELED representation of a Forter decision response. The real payload includes richer recommendation and reason detail.
      properties:
        forterDecision:
          type: string
          description: The Forter recommendation.
          enum:
          - approve
          - decline
          - not reviewed
          - verification requested
        forterToken:
          type: string
          description: The Forter managed token correlating this event.
        reasonCode:
          type: string
        recommendation:
          type: string
    CompensationInput:
      type: object
      description: MODELED compensation request payload.
      properties:
        orderId:
          type: string
        compensationType:
          type: string
          enum:
          - refund
          - reship
        level:
          type: string
          enum:
          - order
          - item
        amount:
          $ref: '#/components/schemas/Amount'
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    Amount:
      type: object
      description: MODELED monetary amount.
      properties:
        amountUSD:
          type: string
        currency:
          type: string
          example: USD
    Error:
      type: object
      description: MODELED error envelope.
      properties:
        status:
          type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials (site ID / API key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication with your Forter API key as the username (empty password). Requests must also carry the `x-forter-siteid` header (your site ID), an `api-version` header (for example `10.1`), and `Content-Type: application/json`. Credentials are provisioned by Forter during onboarding.'