openapi: 3.0.0
info:
  title: Disputes API
  description: REST 2.0 Disputes API
  version: 1.2.8
servers:
  - url: https://api-sandbox.nuvei.com/disputes-api
    description: sandbox
  - url: https://api.nuvei.com/disputes-api
    description: prod
tags:
  - name: Disputes
paths:
  /entities/{entity-id}/disputes:
    get:
      tags:
        - Disputes
      summary: Retrieve List of Disputes
      description: Retrieves a list of disputes for entity based on the provided parameters.
      operationId: getDisputesList
      parameters:
        - name: entity-id
          in: path
          description: Entity Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: from_date
          in: query
          description: From Date
          required: true
          style: form
          explode: true
          schema:
            type: string
            format: date
        - name: to_date
          in: query
          description: To Date
          required: true
          style: form
          explode: true
          schema:
            type: string
            format: date
        - name: response_date_sort
          in: query
          description: Response Date Sort
          required: true
          style: form
          explode: true
          schema:
            type: string
            enum:
              - CreateDate
              - UpdateDate
        - name: retrieve_files
          in: query
          description: Retrieve Files
          required: false
          style: form
          explode: true
          schema:
            type: boolean
            default: false
        - name: offset
          in: query
          description: Offset
          required: false
          style: form
          explode: true
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: Size
          required: false
          style: form
          explode: true
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputesResponse'
      security:
        - Bearer: []
        - ApiKey: []
  /entities/{entity-id}/disputes/{dispute-id}:
    get:
      tags:
        - Disputes
      summary: Retrieve Dispute Details
      description: Retrieves the dispute details for entity based on the provided parameters.
      operationId: getDisputeDetails
      parameters:
        - name: entity-id
          in: path
          description: Entity Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: dispute-id
          in: path
          description: Dispute Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: retrieve_files
          in: query
          description: Retrieve Files
          required: false
          style: form
          explode: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeDetailsResponse'
      security:
        - Bearer: []
        - ApiKey: []
  /entities/{entity-id}/files:
    post:
      tags:
        - Disputes
      summary: Upload Files
      description: Uploads files for later use.
      operationId: postFiles
      parameters:
        - name: entity-id
          in: path
          description: Entity Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFileRequest'
        required: true
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
      security:
        - Bearer: []
        - ApiKey: []
  /entities/{entity-id}/disputes/{dispute-id}/{action}:
    post:
      tags:
        - Disputes
      summary: Perform Dispute Action
      description: Performs an action on a dispute.
      operationId: postDisputeAction
      parameters:
        - name: entity-id
          in: path
          description: Entity Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: dispute-id
          in: path
          description: Dispute Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: action
          in: path
          description: Action
          required: true
          style: simple
          explode: false
          schema:
            $ref: '#/components/schemas/AvailableAction'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeActionRequest'
        required: true
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeActionResponse'
      security:
        - Bearer: []
        - ApiKey: []
components:
  schemas:
    Id:
      title: Id
      type: string
      description: Id
    TransactionId:
      title: TransactionId
      type: integer
      description: Transactionid
      format: int64
    Currency:
      title: Currency
      maxLength: 3
      minLength: 3
      type: string
      description: Currency
    Verdict:
      type: string
      enum:
        - won
        - lost
        - undetermined
        - resolved
    Transaction:
      title: Transaction
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TransactionId'
        date:
          type: string
          format: date-time
        merchantTransactionId:
          type: string
        arn:
          type: string
        amount:
          type: number
        currency:
          $ref: '#/components/schemas/Currency'
      description: Transaction
    AvailableAction:
      title: AvailableActions
      type: string
      description: AvailableActions
      enum:
        - ACCEPT
        - PARTIAL
        - REJECT
    CodeDescription:
      title: CodeDescription
      type: object
      properties:
        code:
          type: string
        description:
          type: string
      description: CodeDescription
    FileId:
      title: FileId
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
      description: FileId
    BaseFile:
      title: BaseFile
      type: object
      properties:
        name:
          type: string
        data:
          type: string
      description: BaseFile
    FileInput:
      title: FileInput
      description: FileInput
      allOf:
        - $ref: '#/components/schemas/FileId'
        - $ref: '#/components/schemas/BaseFile'
    FileUploaded:
      title: FileUploaded
      type: object
      properties:
        correlationId:
          $ref: '#/components/schemas/Id'
        name:
          type: string
      description: FileUploaded
    Event:
      title: Event
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        updateDate:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/CodeDescription'
        disputeAmount:
          type: number
        rejectAmount:
          type: number
        currency:
          $ref: '#/components/schemas/Currency'
        remarks:
          type: string
        disputeReason:
          $ref: '#/components/schemas/CodeDescription'
        rejectReason:
          $ref: '#/components/schemas/CodeDescription'
        files:
          type: array
          items:
            title: FileId
            type: object
            description: FileId
            properties:
              id:
                $ref: '#/components/schemas/Id'
              name:
                type: string
              data:
                type: string
        initiatedBy:
          type: string
          enum:
            - Issuer
            - Acquirer
            - Scheme
      description: Event
    LastDisputeEvent:
      title: LastDisputeEvent
      type: object
      properties:
        lastDisputeEvent:
          $ref: '#/components/schemas/Event'
      description: LastDisputeEvent
    DisputeEvents:
      title: DisputeEvents
      type: object
      properties:
        disputeEvents:
          type: array
          items:
            $ref: '#/components/schemas/Event'
      description: DisputeEvents
    BaseDispute:
      title: Dispute
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        creationDate:
          type: string
          format: date-time
        verdict:
          $ref: '#/components/schemas/Verdict'
        transaction:
          $ref: '#/components/schemas/Transaction'
        paymentOption:
          type: string
        maskedCardNumber:
          type: string
        availableActions:
          type: array
          items:
            $ref: '#/components/schemas/AvailableAction'
      description: Dispute
    Dispute:
      title: Dispute
      description: Dispute
      allOf:
        - $ref: '#/components/schemas/BaseDispute'
        - $ref: '#/components/schemas/LastDisputeEvent'
    DisputeDetails:
      title: DisputeDetails
      description: DisputeDetails
      allOf:
        - $ref: '#/components/schemas/BaseDispute'
        - $ref: '#/components/schemas/DisputeEvents'
    DisputesResponse:
      title: DisputesResponse
      required:
        - result
      type: object
      properties:
        totalCount:
          type: integer
        disputes:
          type: array
          items:
            title: Dispute
            type: object
            description: Dispute
            properties:
              id:
                $ref: '#/components/schemas/Id'
              creationDate:
                type: string
                format: date-time
              verdict:
                $ref: '#/components/schemas/Verdict'
              transaction:
                $ref: '#/components/schemas/Transaction'
              paymentOption:
                type: string
              maskedCardNumber:
                type: string
              availableActions:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableAction'
              lastDisputeEvent:
                $ref: '#/components/schemas/Event'
        result:
          $ref: '#/components/schemas/BaseApiResultOutput'
      description: DisputesResponse
    DisputeDetailsResponse:
      title: DisputeDetailsResponse
      required:
        - result
      type: object
      properties:
        disputes:
          $ref: '#/components/schemas/DisputeDetails'
        result:
          $ref: '#/components/schemas/BaseApiResultOutput'
      description: DisputeDetailsResponse
    UploadFileRequest:
      title: UploadFileRequest
      required:
        - file
      type: object
      properties:
        file:
          $ref: '#/components/schemas/BaseFile'
      description: UploadFileRequest
    UploadFileResponse:
      title: UploadFieldResponse
      required:
        - result
      type: object
      properties:
        file:
          $ref: '#/components/schemas/FileUploaded'
        result:
          $ref: '#/components/schemas/BaseApiResultOutput'
      description: UploadFileResponse
    DisputeActionRequest:
      title: DisputeActionRequest
      type: object
      properties:
        acceptedAmount:
          type: number
        currency:
          $ref: '#/components/schemas/Currency'
        cardholderNoLongerDisputes:
          type: boolean
          default: false
        notes:
          maxLength: 100
          type: string
        files:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/Id'
      description: DisputeActionRequest
    DisputeActionResponse:
      title: DisputeActionResponse
      required:
        - result
      type: object
      properties:
        disputeEventId:
          $ref: '#/components/schemas/Id'
        transactionId:
          $ref: '#/components/schemas/TransactionId'
        result:
          $ref: '#/components/schemas/BaseApiResultOutput'
      description: DisputeActionResponse
    BaseApiResultOutput:
      required:
        - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BaseResultStatus'
        errors:
          $ref: '#/components/schemas/ResultError'
    BaseResultStatus:
      type: string
      description: 'Status of the request: success | error'
      enum:
        - success
        - error
    ResultError:
      required:
        - code
      type: object
      properties:
        code:
          maxLength: 11
          type: string
          description: If an error occurred on the request side, an error code is returned in this parameter.
          example: '7000.1000'
        reason:
          maxLength: 400
          type: string
          description: If an error occurred on the request side, then an error reason is returned in this parameter.
          example: Internal Processing Error
        reference:
          maxLength: 400
          type: string
          description: Reference value for troubleshooting
          example: '110.1260'
      description: If an error occurred on the request side, an error code is returned in this parameter.
  parameters:
    entity-id:
      name: entity-id
      in: path
      description: Entity Id
      required: true
      style: simple
      explode: false
      schema:
        type: string
    dispute-id:
      name: dispute-id
      in: path
      description: Dispute Id
      required: true
      style: simple
      explode: false
      schema:
        type: string
    action:
      name: action
      in: path
      description: Action
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/AvailableAction'
    from_date:
      name: from_date
      in: query
      description: From Date
      required: true
      style: form
      explode: true
      schema:
        type: string
        format: date
    to_date:
      name: to_date
      in: query
      description: To Date
      required: true
      style: form
      explode: true
      schema:
        type: string
        format: date
    response_date_sort:
      name: response_date_sort
      in: query
      description: Response Date Sort
      required: true
      style: form
      explode: true
      schema:
        type: string
        enum:
          - CreateDate
          - UpdateDate
    receive_files:
      name: retrieve_files
      in: query
      description: Retrieve Files
      required: false
      style: form
      explode: true
      schema:
        type: boolean
        default: false
    offset:
      name: offset
      in: query
      description: Offset
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 0
    size:
      name: size
      in: query
      description: Size
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 100
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKey:
      type: apiKey
      name: X-API-KEY
      in: header