Forter Chargeback and Compensation API

openapi: 3.0.3
info:
  title: Forter 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: Orders
    description: Order and checkout fraud/abuse decisions and order status.
  - name: Accounts
    description: Signup and login (account takeover) decisions.
  - name: Disputes
    description: Chargeback disputes and customer compensation requests.
  - name: Data Privacy
    description: Data-subject profile access for privacy and compliance.
paths:
  /v2/orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: submitOrderV2
      tags:
        - Orders
      summary: Submit an order for a decision (v2)
      description: >-
        Send order and checkout information at checkout to receive a real-time
        fraud or abuse decision. The response may also carry payment
        optimization or abuse-prevention recommendations.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com. Request/response schema
        MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: A Forter decision for the order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: submitOrderV3
      tags:
        - Orders
      summary: Submit an order for a decision (v3)
      description: >-
        Version 3 of the order decision endpoint. Same intent as v2 - submit
        order/checkout data and receive a fraud or abuse decision - with the v3
        request/response shape.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com (Order v3).
        Request/response schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: A Forter decision for the order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/status/{orderId}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: submitOrderStatus
      tags:
        - Orders
      summary: Report order status
      description: >-
        Report the downstream lifecycle status of an order back to Forter (for
        example, that it was captured, shipped, cancelled, or refunded). No
        decision is returned; this input improves the model.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com (Order status).
        Request schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatusInput'
      responses:
        '200':
          description: Acknowledgement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ack'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/signup/{accountId}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    post:
      operationId: submitSignup
      tags:
        - Accounts
      summary: Submit a signup for a decision
      description: >-
        Send account registration information at signup to receive a fraud or
        abuse decision for the new account.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com (Signup).
        Request/response schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountEventInput'
      responses:
        '200':
          description: A Forter decision for the signup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/authentication-result/{loginId}:
    parameters:
      - name: loginId
        in: path
        required: true
        description: A unique identifier for the login / authentication event.
        schema:
          type: string
    post:
      operationId: submitAuthenticationResult
      tags:
        - Accounts
      summary: Submit a login / authentication result for an ATO decision
      description: >-
        Send login attempt information to receive an account takeover (ATO)
        decision. Used to protect the login flow with Forter's identity graph.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com (Authentication result).
        Request/response schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountEventInput'
      responses:
        '200':
          description: A Forter account takeover decision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /v2/accounts/profile-access/{id}:
    parameters:
      - $ref: '#/components/parameters/GenericId'
    post:
      operationId: submitProfileAccess
      tags:
        - Data Privacy
      summary: Data-subject profile access
      description: >-
        Profile access endpoint used to support privacy and compliance
        workflows against the identity data Forter holds for an account.
      x-forter-status: >-
        Path/method confirmed against docs.forter.com (Profile access).
        Request/response schema MODELED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileAccessInput'
      responses:
        '200':
          description: Acknowledgement or profile-access result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ack'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      description: A unique identifier for the order, generated by the merchant.
      schema:
        type: string
    AccountId:
      name: accountId
      in: path
      required: true
      description: A unique identifier for the account.
      schema:
        type: string
    GenericId:
      name: id
      in: path
      required: true
      description: A unique identifier for the resource / event.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials (site ID / API key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: MODELED error envelope.
      properties:
        status:
          type: string
        message:
          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
    OrderInput:
      type: object
      description: >-
        MODELED subset of the order/checkout payload. Real orders include
        detailed buyer, cart, payment, shipping, and connection information.
      properties:
        orderId:
          type: string
        checkoutTime:
          type: integer
          description: Epoch seconds when checkout occurred.
        totalAmount:
          $ref: '#/components/schemas/Amount'
        primaryDeliveryDetails:
          type: object
          additionalProperties: true
        cartItems:
          type: array
          items:
            type: object
            additionalProperties: true
        accountOwner:
          type: object
          additionalProperties: true
        payment:
          type: array
          items:
            type: object
            additionalProperties: true
        connectionInformation:
          type: object
          additionalProperties: true
    OrderStatusInput:
      type: object
      description: MODELED order status payload.
      properties:
        orderId:
          type: string
        updatedStatus:
          type: string
          enum:
            - AUTHORIZATION_REQUESTED
            - CAPTURED
            - CANCELED_BY_MERCHANT
            - CANCELED_BY_CUSTOMER
            - SHIPPED
            - REFUNDED
            - COMPLETED
        updateTime:
          type: integer
    AccountEventInput:
      type: object
      description: >-
        MODELED subset for signup and login events (registration or
        authentication details plus connection information).
      properties:
        accountId:
          type: string
        eventTime:
          type: integer
        loginMethod:
          type: string
        accountData:
          type: object
          additionalProperties: true
        connectionInformation:
          type: object
          additionalProperties: true
    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
    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
    ProfileAccessInput:
      type: object
      description: MODELED profile-access (data privacy) payload.
      properties:
        accountId:
          type: string
        requestType:
          type: string
          example: access
    Amount:
      type: object
      description: MODELED monetary amount.
      properties:
        amountUSD:
          type: string
        currency:
          type: string
          example: USD