{ "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" } } } }