{
  "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.\n\nA valid JWT token is required in order to perform requests against this API.\nSee [Ratepay Authentication API](/apis/authentication/openapi/authentication_api) specification.\n",
        "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.\n\nA valid JWT token is required in order to perform requests against this API.\nSee [Ratepay Authentication API](/apis/authentication/openapi/authentication_api) specification.\n",
        "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.\n\nA valid JWT token is required in order to perform requests against this API.\nSee [Ratepay Authentication API](/apis/authentication/openapi/authentication_api) specification.\n",
        "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.\n\nA valid JWT token is required in order to perform requests against this API.\nSee [Ratepay Authentication API](/apis/authentication/openapi/authentication_api) specification.\n",
        "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.\nAllowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'. Maximum file size is 10 MB.\n"
      },
      "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.\n",
            "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'\n"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "DELIVERED",
              "RETURNED",
              "LOST"
            ],
            "description": "Current status of delivery.\n"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date when goods were delivered.\nMust be in the format YYYY-MM-DD, in accordance with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).\n",
            "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.\nCountry code in accordance with [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)\n"
          },
          "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.\nThe delivery note is required only in case of multiple captures, if the captures did not contain item information.\n"
          }
        }
      },
      "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.\n"
          }
        }
      },
      "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.\n"
              }
            }
          }
        ]
      },
      "EvidenceWithDeliveryInformation": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Evidence"
          },
          {
            "type": "object",
            "required": [
              "delivery_information"
            ],
            "properties": {
              "delivery_information": {
                "type": "array",
                "description": "List of objects containing delivery details.\n",
                "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.\nThis information is required if no delivery information or additional evidence has been provided.\n"
              },
              "delivery_information": {
                "type": "array",
                "description": "List of objects containing delivery details.\nThis information is required if no case details or additional evidence has been provided.\n",
                "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.\nAllowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'. Maximum file size is 10 MB.\nThis information is required if no delivery information or case details have been provided.\n"
          },
          "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.\nAllowed types are '.zip', '.pdf', '.jpg', '.png', '.gif', '.txt'. Maximum file size is 10 MB.\n"
      }
    }
  }
}