openapi: 3.0.1
info:
  title: Dispute OpenAPI Specification
  description: >-
    This is the documentation for the Ratepay Dispute API. The API is still in
    development and subject to change. This documentation will evolve as the
    development of the API progresses.
  contact:
    name: Ratepay
    url: https://www.ratepay.com/
    email: info@ratepay.com
  version: version
servers:
  - url: https://api-integration.ratepay.com/dispute/management
    description: Ratepay Integration Platform
security:
  - Bearer Authentication: []
paths:
  /v1/disputes/{ratepay_dispute_id}/evidences/item-not-received:
    post:
      summary: Provide evidence for ITEM_NOT_RECEIVED
      operationId: ItemNotReceived
      description: >
        Endpoint to provide evidence for the ITEM_NOT_RECEIVED request for
        information.


        A valid JWT token is required in order to perform requests against this
        API.

        See [Ratepay Authentication
        API](/apis/authentication/openapi/authentication_api) specification.
      parameters:
        - $ref: '#/components/parameters/ratepay_dispute_id'
        - name: Authorization
          in: header
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See                       [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ItemNotReceivedContent'
      responses:
        '201':
          description: Evidence was created.
        '404':
          description: Incorrect path parameters or invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  The requested resource was not found. Please refer to the
                  documentation for the list of resources.
        '409':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Evidence already exists.
        '422':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/InvalidDataResponseForItemNotReceivedAndDefend
  /v1/disputes/{ratepay_dispute_id}/evidences/item-returned:
    post:
      summary: Provide evidence for ITEM_RETURNED
      operationId: ItemReturned
      description: >
        Endpoint to provide evidence for the ITEM_RETURNED request for
        information.


        A valid JWT token is required in order to perform requests against this
        API.

        See [Ratepay Authentication
        API](/apis/authentication/openapi/authentication_api) specification.
      parameters:
        - $ref: '#/components/parameters/ratepay_dispute_id'
        - name: Authorization
          in: header
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See                       [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ItemReturnedContent'
      responses:
        '201':
          description: Evidence was created.
        '404':
          description: Incorrect path parameters or invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  The requested resource was not found. Please refer to the
                  documentation for the list of resources.
        '409':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Evidence already exists.
        '422':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidDataResponseForItemReturnedOrFraud'
  /v1/disputes/{ratepay_dispute_id}/evidences/defend:
    post:
      summary: Provide evidence for DEFEND
      operationId: Defend
      description: >
        Endpoint to provide evidence for the DEFEND request for information.


        A valid JWT token is required in order to perform requests against this
        API.

        See [Ratepay Authentication
        API](/apis/authentication/openapi/authentication_api) specification.
      parameters:
        - $ref: '#/components/parameters/ratepay_dispute_id'
        - name: Authorization
          in: header
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See                       [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DefendContent'
      responses:
        '201':
          description: Evidence was created.
        '404':
          description: Incorrect path parameters or invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  The requested resource was not found. Please refer to the
                  documentation for the list of resources.
        '409':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Evidence already exists.
        '422':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/InvalidDataResponseForItemNotReceivedAndDefend
  /v1/disputes/{ratepay_dispute_id}/evidences/fraud:
    post:
      summary: Provide evidence for FRAUD
      operationId: Fraud
      description: >
        Endpoint to provide evidence for the FRAUD request for information.


        A valid JWT token is required in order to perform requests against this
        API.

        See [Ratepay Authentication
        API](/apis/authentication/openapi/authentication_api) specification.
      parameters:
        - $ref: '#/components/parameters/ratepay_dispute_id'
        - name: Authorization
          in: header
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See                       [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FraudContent'
      responses:
        '201':
          description: Evidence was created.
        '404':
          description: Incorrect path parameters or invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  The requested resource was not found. Please refer to the
                  documentation for the list of resources.
        '409':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Evidence already exists.
        '422':
          description: Unable to process request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidDataResponseForItemReturnedOrFraud'
components:
  parameters:
    ratepay_dispute_id:
      in: path
      name: ratepay_dispute_id
      required: true
      schema:
        type: string
        minLength: 20
        maxLength: 20
        pattern: ^[A-Za-z0-9-_]{20}$
        example: OpK7rRZP0GND8MobcIKA
        description: Ratepay dispute ID
  securitySchemes:
    Bearer Authentication:
      type: http
      description: >-
        For each request, a valid access token must be provided in the
        Authorization header. See [Authentication
        API](/docs/developer/authentication/authentication/) for obtaining a
        valid token.
      scheme: bearer
      bearerFormat: JWT
  schemas:
    AdditionalEvidence:
      type: string
      format: binary
      description: >
        File with additional evidence.

        Allowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'.
        Maximum file size is 10 MB.
    DefendContent:
      type: object
      required:
        - evidence
      properties:
        evidence:
          $ref: '#/components/schemas/EvidenceWithDeliveryInformation'
        additional_evidence:
          $ref: '#/components/schemas/AdditionalEvidence'
        file1:
          $ref: '#/components/schemas/NoteFile'
    DeliveryInformation:
      type: object
      required:
        - carrier_name
        - tracking_number
      properties:
        carrier_name:
          type: string
          description: |
            Name of the shipping carrier used by the shop for the capture.
          enum:
            - DHL
            - UPS
            - POST_AUSTRIA
            - DPD
            - SWISS_POST
            - GLS
            - ASENDIA
            - HERMES_LOGISTICS
            - FEDEX
            - OTHER_WITH_TRACKING
            - OTHER_WITHOUT_TRACKING
        tracking_number:
          type: string
          minLength: 1
          maxLength: 127
          example: 2.3834745636235124e+23
          description: >
            Tracking number for order delivery. This field is optional for
            carrier_name: 'OTHER_WITHOUT_TRACKING'
        status:
          type: string
          enum:
            - PENDING
            - DELIVERED
            - RETURNED
            - LOST
          description: |
            Current status of delivery.
        date:
          type: string
          format: date
          description: >
            Date when goods were delivered.

            Must be in the format YYYY-MM-DD, in accordance with [ISO
            8601](https://en.wikipedia.org/wiki/ISO_8601).
          example: '2019-05-17'
        address:
          type: string
          minLength: 1
          maxLength: 127
          pattern: ^[\w\s]+\s[\d]+,\s[\d]{5}\s[A-Z]{2}$
          example: Alpenstrasse 21, 15432 DE
          description: >
            Delivery address.

            Country code in accordance with
            [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
        note:
          type: string
          minLength: 1
          maxLength: 127
          pattern: ^[A-Za-z0-9-]+$
          description: >
            Name of the delivery note file to be uploaded. The value will be
            used as a key to the binary file in the request.

            The delivery note is required only in case of multiple captures, if
            the captures did not contain item information.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    Evidence:
      type: object
      required:
        - ratepay_transaction_id
      properties:
        ratepay_transaction_id:
          type: string
          minLength: 20
          maxLength: 127
          pattern: ^[A-Za-z0-9-_]{20,127}$
          example: scwBgARW-nE93I7_ywhp
          description: |
            Ratepay transaction ID.
    EvidenceWithCaseDetails:
      allOf:
        - $ref: '#/components/schemas/Evidence'
        - type: object
          required:
            - case_details
          properties:
            case_details:
              type: string
              example: Information regarding the case xyz
              description: >
                Details on the shop agreeing with the request regarding the
                returned goods.
    EvidenceWithDeliveryInformation:
      allOf:
        - $ref: '#/components/schemas/Evidence'
        - type: object
          required:
            - delivery_information
          properties:
            delivery_information:
              type: array
              description: |
                List of objects containing delivery details.
              items:
                $ref: '#/components/schemas/DeliveryInformation'
    FullEvidence:
      allOf:
        - $ref: '#/components/schemas/Evidence'
        - type: object
          properties:
            case_details:
              type: string
              example: Information regarding the case xyz
              description: >
                All details available to the shop regarding the return of goods.

                This information is required if no delivery information or
                additional evidence has been provided.
            delivery_information:
              type: array
              description: >
                List of objects containing delivery details.

                This information is required if no case details or additional
                evidence has been provided.
              items:
                $ref: '#/components/schemas/DeliveryInformation'
    FraudContent:
      type: object
      required:
        - evidence
      properties:
        evidence:
          $ref: '#/components/schemas/FullEvidence'
        additional_evidence:
          allOf:
            - $ref: '#/components/schemas/AdditionalEvidence'
          description: >
            File with additional evidence.

            Allowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'.
            Maximum file size is 10 MB.

            This information is required if no delivery information or case
            details have been provided.
        file1:
          $ref: '#/components/schemas/NoteFile'
    ItemNotReceivedContent:
      type: object
      required:
        - evidence
      properties:
        evidence:
          $ref: '#/components/schemas/EvidenceWithDeliveryInformation'
        additional_evidence:
          $ref: '#/components/schemas/AdditionalEvidence'
        file1:
          $ref: '#/components/schemas/NoteFile'
    ItemReturnedContent:
      type: object
      required:
        - evidence
      properties:
        evidence:
          $ref: '#/components/schemas/EvidenceWithCaseDetails'
        additional_evidence:
          $ref: '#/components/schemas/AdditionalEvidence'
    InvalidDataResponseForItemNotReceivedAndDefend:
      type: object
      description: Information about why the request failed.
      properties:
        message:
          type: string
          example: Mandatory information missing.
        errors:
          type: object
          properties:
            field_name:
              type: array
              items:
                type: string
          example:
            message: The submitted data is invalid.
            evidence:
              - The Ratepay transaction ID is required.
              - The delivery_information.0.carrier_name is required.
              - The delivery_information.0.tracking_number is required.
    InvalidDataResponseForItemReturnedOrFraud:
      type: object
      description: Information about why the request failed.
      properties:
        message:
          type: string
          example: Mandatory information missing.
        errors:
          type: object
          properties:
            field_name:
              type: array
              items:
                type: string
          example:
            message: The submitted data is invalid.
            evidence:
              - The Ratepay transaction ID is required.
              - The case details are required.
    NoteFile:
      type: string
      format: binary
      description: >
        Information about the items included in the shipment. Key name must
        correspond to the actual value of the `evidence` field.

        Allowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'.
        Maximum file size is 10 MB.
