{"openapi":"3.0.1","info":{"title":"Disputes","version":"Disputes-API-v1.3.0.Final","contact":{"name":"Fiserv EMEA Developer Portal","url":"https://fiserv.dev/support","email":"support@20080132.hubspot-inbox.com"},"description":"Welcome to our Disputes API. This API allows you to manage every part of the Dispute lifecycle.","termsOfService":"https://fiserv.dev/legal"},"servers":[{"url":"https://prod.emea.api.fiservapps.com/sandbox/exp/v1","description":"Sandbox"},{"url":"https://prod.emea.api.fiservapps.com/exp/v1","description":"Production"}],"paths":{"/disputes":{"get":{"summary":"List disputes","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Dispute-Simple"}},"examples":{}}},"headers":{"Has-More-Records":{"schema":{"type":"boolean"},"description":"Returns whether are not there are more items that can be returned"},"Total-Count":{"schema":{"type":"integer"},"description":"Returns the total count of items"},"Trace-Id":{"schema":{"type":"string","format":"uuid"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"get-disputes","description":"Search for Disputes.","parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"schema":{"type":"string","example":"74720942152221525431867","minLength":23,"maxLength":24,"pattern":"^[0-9]{23,24}$"},"in":"query","name":"acquirerReferenceNumber","description":"Find disputes using the Acquirer Reference Number linked to the original transaction."},{"schema":{"type":"string","format":"date","example":"2022-06-02"},"in":"query","name":"from","description":"Filter Disputes from a certain date when the dispute was first created. Format YYYY-MM-DD."},{"schema":{"type":"string","example":"2022-07-28","format":"date"},"in":"query","name":"to","description":"Filter Disputes to a certain date when the dispute was first created. Format YYYY-MM-DD."},{"schema":{"type":"integer","format":"int32","default":20,"maximum":100,"minimum":1},"in":"query","name":"limit","description":"Number of elements to be returned in a single query. Can be used for page/offset or cursor based pagination"},{"schema":{"type":"integer","format":"int32","minimum":0,"maximum":2147483647,"example":0},"in":"query","name":"offset","description":"Starting point to start retrieving the elements from. It is \"0\" based i.e. value \"0\" signifies the first page. This can be used with \"limit\". Can be used for page/offset based pagination."},{"schema":{"type":"string","example":"1000000000","minLength":0,"maxLength":20,"pattern":"^[0-9]{0,20}$"},"in":"query","name":"visaId","description":"Filter Disputes by Visa Resolve Online Id number"},{"schema":{"type":"string","example":"1000000000","minLength":0,"maxLength":19,"pattern":"^[0-9]{0,19}$"},"in":"query","name":"mastercardId","description":"Filter Disputes by MasterCard's Claim Manager ID"},{"schema":{"type":"string","example":"79754762"},"in":"query","name":"orderId","description":"Filter Disputes by a Merchant Transaction Reference (Order ID)"},{"schema":{"type":"string","enum":["OPEN","CLOSED","IN_PROGRESS"],"example":"OPEN","default":"OPEN"},"in":"query","name":"status","description":"Open cases are those awaiting an action. In Progress cases are where an action was taken and need to be submitted to the scheme or cases that are waiting if the issuer will continue to dispute the transaction. Closed cases have no further action that can be taken by the issuer or acquirer"},{"schema":{"type":"string","example":"-stage"},"in":"query","name":"sort","description":"Defines how to sort the records returned. Must be specified in the syntax \"+\" (ascending) or \"-\" (descending) followed by the field name. For example: \"+posted\" would sort by the \"posted\" field ascending."},{"schema":{"type":"string","example":"174062834992","pattern":"^[0-9]{0,20}$","minLength":0,"maxLength":20},"in":"query","name":"merchantId","description":"Filter disputes by Merchant Id."},{"$ref":"#/components/parameters/stage"}],"tags":["Endpoints"]}},"/disputes/{disputeId}":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/disputeId"}],"get":{"summary":"Retrieve a single dispute by Id","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}},"headers":{"Trace-Id":{"schema":{"type":"string","format":"uuid"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"get-disputes-id","description":"Get Dispute by ID","tags":["Endpoints"],"parameters":[]}},"/disputes/{disputeId}/documents/{documentId}":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/documentId"},{"$ref":"#/components/parameters/disputeId"}],"get":{"summary":"Retrieve Dispute Document by ID","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"application/xml":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"convert/xmltojson":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"application/pdf":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"image/tif":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"image/tiff":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"image/jpg":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"image/jpeg":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"application/msword":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary","description":"Binary content of the file.","minLength":1}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"get-disputes-id-documents-documentId","description":"Get document by ID for a given Dispute ID","parameters":[{"schema":{"type":"string","example":"*/*"},"in":"header","name":"Accept","description":"Specifies the desired document format to return. The allowed valid values are 'application/xml', 'application/pdf', 'image/tif', 'image/tiff', 'image/jpg', 'image/jpeg', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'convert/xmltojson' and the value shown in example. To retrieve the document regardless of its stored format, set this field to the value as shown in example. If a specific format is provided, the API will return the document only if it matches that format; otherwise no document is returned. If the document is in XML format and to request conversion from XML to JSON, set the value to 'convert/xmltojson'.","required":true}],"tags":["Endpoints"]}},"/disputes/{disputeId}/events/{eventId}/actions":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/disputeId"},{"$ref":"#/components/parameters/eventId"}],"post":{"summary":"Execute an Action","operationId":"post-disputes-disputeId-actions-actionId","responses":{"204":{"description":"OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"description":"Execute an Action against this Dispute","tags":["Endpoints"],"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/Message-Signature"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/Action-Code"},"tcn":{"$ref":"#/components/schemas/Tcn"}},"required":["code","tcn"],"description":"\"code\" and \"tcn\" fields describing the action to be taken should be provided. In addition to these fields, the required data fields based on the kind of action requested also needs to be provided. To get list of required data fields for the respective allowed action, use \"GET Disputes by Id\" endpoint for the particular disputeId (in API response, refer data in events-->allowedActions-->requiredDataFields object)."},"examples":{"Execute an action":{"value":{"code":"040","tcn":"-1662613832"}}}}}}}},"/disputes/{disputeId}/actions/{actionId}/undo":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/disputeId"},{"$ref":"#/components/parameters/actionId"}],"post":{"summary":"Undo an Action","operationId":"post-disputes-disputeId-actions-actionId-undo","responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"description":"Undo an Action","tags":["Endpoints"],"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/Message-Signature"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tcn":{"$ref":"#/components/schemas/Tcn"}},"required":["tcn"]},"examples":{"Undo an action":{"value":{"tcn":"-1662613832"}}}}},"description":"Undo can be performed for the action taken previously, provided that it was not yet processed in the daily cycle"},"x-stoplight":{"id":"r3qtyn9zbjq4e"}}},"/disputes/{disputeId}/notes":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/disputeId"}],"post":{"summary":"Add a Note","operationId":"post-disputes-disputeId-notes","responses":{"201":{"description":"Note created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute-Note-Response"}}},"headers":{"Trace-Id":{"schema":{"type":"string","format":"uuid"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"description":"Add a new note to a Dispute to provide more detail and information.","tags":["Endpoints"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note-Create"},"examples":{"Add a note":{"value":{"tcn":"-1662613832","content":"Oh what a lovely note!"}}}}},"description":"Add a note to the Dispute Case. Once added, then it cannot be updated but additional notes can be added."},"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/Message-Signature"}]}},"/disputes/{disputeId}/document":{"parameters":[{"$ref":"#/components/parameters/Institution-Number"},{"$ref":"#/components/parameters/Message-Signature"},{"name":"disputeId","in":"path","schema":{"type":"integer","format":"int64","example":20210720959791,"minimum":19000101000000,"maximum":99991231999999},"description":"Unique case identifier assigned to the dispute.","required":true}],"post":{"summary":"Add a Document","operationId":"add-document","responses":{"201":{"description":"Document attached successfully to the Case Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Add-Document-Response"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/AccessForbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"evidence":{"type":"string","format":"binary","description":"Evidence such as photographs or emails, to prove a link between the person receiving the merchandise or services and the cardholder, or to prove that the cardholder disputing the transaction is in possession of the merchandise and/or is using the services. Supported formats: JPG, JPEG, TIF, TIFF, PDF, DOCX, DOC. Maximum supported file size is 5MB."},"templateCategoryCode":{"$ref":"#/components/schemas/TemplateCategoryCode"},"documentNote":{"$ref":"#/components/schemas/DocumentNote"},"tcn":{"$ref":"#/components/schemas/Tcn"},"networkFormType":{"type":"string","description":"Indicates the name of the network form that is associated with the letter or attachment and belongs to the card scheme. Valid values are VISA_NETWORK_FORM, MASTERCARD_NETWORK_FORM and JCB_NETWORK_FORM.","example":"VISA_NETWORK_FORM","enum":["VISA_NETWORK_FORM","MASTERCARD_NETWORK_FORM","JCB_NETWORK_FORM"]}},"required":["evidence","templateCategoryCode","tcn","networkFormType"]}}}},"tags":["Endpoints"],"description":"This endpoint can be used to attach additional documents to the Dispute Case. One document per API call is allowed."}}},"components":{"schemas":{"Dispute":{"title":"Dispute","type":"object","description":"An individual dispute case.","properties":{"id":{"type":"integer","format":"int64","example":20220602835125,"minimum":19000101000000,"maximum":99991231999999,"description":"Unique case identifier assigned to the dispute."},"status":{"type":"string","description":"Current status of the dispute.","example":"OPEN","enum":["OPEN","IN_PROGRESS","CLOSED"]},"stageCode":{"$ref":"#/components/schemas/Stage"},"stageDescription":{"type":"string","example":"Dispute","description":"Description of the current Dispute Stage."},"result":{"type":"string","description":"The result of this dispute towards the merchant.","enum":["WON","LOST","LETTER","SPLIT"],"example":"WON"},"lastAction":{"type":"string","format":"date-time","description":"Date and Time the last action was taken for the dispute. ISO 8601 format.","example":"2022-06-02T10:43:22Z"},"posted":{"type":"string","format":"date","description":"Date when the original dispute was posted into the Acquirer platform.","example":"2022-06-02"},"due":{"type":"string","format":"date","description":"Due date to take action on the dispute.","example":"2022-07-28"},"workByDate":{"type":"string","format":"date","description":"Indicates the last date when the merchant can take action on the chargeback, formatted as YYYY-MM-DD. The workByDate is calculated for the merchant's reference based on the acquirer's configuration. The acquirer reserves a few days from the overall due date and provides the remaining days for merchants to review and act, allowing the acquirer to assess the merchant's action and make a final decision accordingly.","example":"2022-07-21"},"cardScheme":{"$ref":"#/components/schemas/Scheme"},"cardIssuer":{"type":"string","description":"Name of the card issuing organization.","pattern":"^[A-Za-z0-9.-_ :]{0,32}$","example":"RBS"},"mastercardId":{"type":"string","title":"Mastercard ID","description":"Mastercard's Claim Manager ID. This is the unique identifier given by Mastercard's disputes handling system.","minLength":0,"maxLength":19,"pattern":"^[0-9]{0,19}$","example":"6549873216549876545"},"acquirerReferenceNumber":{"$ref":"#/components/schemas/Arn"},"reasonCode":{"type":"string","example":"441","description":"The code that represents the reason for a dispute within the card scheme."},"reasonDescription":{"type":"string","example":"CBK: Processing Error","description":"The description of the dispute reason code."},"visaConditionCode":{"type":"string","description":"The code that represents the sub category of the dispute reason code within the card scheme.","example":"4"},"visaConditionDescription":{"type":"string","description":"The description for the subcategory code of dispute condition.","example":"Incorrect Account Number"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency-Code"},"visaId":{"type":"string","description":"Visa Resolve Online Id number. This is the unique identifier given by Visa's disputes handling system.","example":"1000000000","minLength":0,"maxLength":20,"pattern":"^[0-9]{0,20}$"},"tcn":{"description":"Unique Transaction Control Number assigned to the dispute. This number is used in subsequent actions to ensure your actions are not submitted or processed multiple times.","type":"string","example":"-1662613832"},"merchantId":{"type":"string","minLength":0,"maxLength":20,"pattern":"^[0-9]{0,20}$","description":"OmniPay external Merchant number.","example":"174062834992"},"merchantName":{"maxLength":25,"minLength":1,"pattern":"^(?!\\s*$).+","type":"string","description":"Merchant Name.","example":"KFC"},"merchantTransactionRef":{"type":"string","pattern":"^[a-zA-Z0-9À-ý_ \\.\\&\\,\\-]{0,23}$","minLength":0,"maxLength":23,"description":"Merchant's original transaction reference.","example":"79754762"},"closedDate":{"type":"string","format":"date-time","description":"Date when the case moved to CLOSED status. Format YYYY-MM-DDTHH:mm:ssZ.","example":"2019-08-24T14:15:22Z"},"transactions":{"type":"array","description":"List of transactions related to this dispute","items":{"$ref":"#/components/schemas/Transaction"}},"authorisations":{"type":"array","description":"List of authorisations","items":{"$ref":"#/components/schemas/Authorisation"}},"documents":{"type":"array","description":"List of documents related to this dispute","items":{"$ref":"#/components/schemas/Document"}},"events":{"type":"array","description":"A list of events that have taken place on this dispute and can be responded to","items":{"$ref":"#/components/schemas/Event"}},"notes":{"type":"array","description":"List of notes related to the dispute","items":{"$ref":"#/components/schemas/Note"}}}},"Dispute-Simple":{"title":"Dispute Simple","description":"A dispute object to use when summarising or listing disputes","allOf":[{"type":"object","properties":{"id":{"$ref":"#/components/schemas/Dispute-Id"},"status":{"$ref":"#/components/schemas/Status"},"stageCode":{"$ref":"#/components/schemas/Stage"},"stageDescription":{"$ref":"#/components/schemas/Stage-Description"},"result":{"$ref":"#/components/schemas/Result"},"lastAction":{"$ref":"#/components/schemas/Last-Action"},"posted":{"$ref":"#/components/schemas/Posted"},"due":{"$ref":"#/components/schemas/Due"},"workByDate":{"$ref":"#/components/schemas/workByDate"},"cardScheme":{"$ref":"#/components/schemas/Scheme"},"cardIssuer":{"$ref":"#/components/schemas/Card-Issuer"},"acquirerReferenceNumber":{"$ref":"#/components/schemas/Arn"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency-Code"},"visaId":{"$ref":"#/components/schemas/Visa-Id"},"mastercardId":{"$ref":"#/components/schemas/Mastercard-Id"},"merchantId":{"$ref":"#/components/schemas/Merchant-Id"},"merchantTransactionRef":{"$ref":"#/components/schemas/Merchant-Transaction-Ref"},"tcn":{"$ref":"#/components/schemas/Tcn"},"closedDate":{"type":"string","format":"date-time","description":"Date when the case moved to CLOSED status. Format YYYY-MM-DDTHH:mm:ssZ.","example":"2019-08-24T14:15:22Z"},"institutionNumber":{"type":"string","minLength":8,"maxLength":8,"description":"OmniPay internal Institution Number.","example":"00000001"}}},{"$ref":"#/components/schemas/Reason-Code-Description"}]},"Transaction":{"title":"Dispute-Transaction","type":"object","description":"A transaction is the original purchase transaction and relevant refunds.","properties":{"id":{"description":"Transaction ID","type":"integer","format":"int64","example":20220602695614,"minimum":19000101000000,"maximum":99991231999999},"date":{"type":"string","format":"date-time","description":"Date of the Transaction","example":"2022-06-01T00:00:00Z"},"transactionKindCode":{"type":"string","description":"Transaction Kind code.","example":"110","pattern":"^[0-9]{1,3}$","minLength":1,"maxLength":3},"transactionKindDescription":{"type":"string","description":"Transaction Kind description.","example":"Presentment","pattern":"^[A-Za-z0-9.-_ :]{0,128}$","minLength":0,"maxLength":128},"typeCode":{"type":"string","example":"005","description":"Code indicating the type of transaction"},"typeDescription":{"type":"string","example":"Purchase","description":"Description for the type of transaction"},"captureMethodCode":{"type":"string","description":"Code indicating the type of capture method used in this transaction","example":"054"},"captureMethodDescription":{"type":"string","description":"Description of the type of capture method used in this transaction","example":"eCommerce, Channel Encrypt"},"schemeProcessedDate":{"type":"string","description":"The date the card scheme processed the transaction.","format":"date","example":"2019-08-21"},"posted":{"type":"string","format":"date","example":"2022-06-01","description":"Date the transaction was posted"},"cardNumber":{"type":"string","description":"The card number associated with the transaction with relevant obfuscation/masking and encryption","example":"400203XXCJYR0008","pattern":"^[A-Z0-9]{12,19}$","minLength":12,"maxLength":19},"originalTransactionAmount":{"$ref":"#/components/schemas/Amount"},"originalTransactionCurrency":{"$ref":"#/components/schemas/Currency-Code"},"networkSettlementAmount":{"$ref":"#/components/schemas/Amount"},"networkSettlementCurrency":{"$ref":"#/components/schemas/Currency-Code"},"merchantFundingAmount":{"$ref":"#/components/schemas/Amount"},"merchantFundingCurrency":{"$ref":"#/components/schemas/Currency-Code"},"reversal":{"type":"boolean","description":"Is this transaction a reversal of a previous transaction?","example":false},"duplicate":{"type":"boolean","description":"Is this transaction a duplicate of a previous transaction?","example":false},"arn":{"$ref":"#/components/schemas/Arn"},"authCode":{"$ref":"#/components/schemas/Auth-Code"}}},"Event":{"title":"Event","allOf":[{"type":"object","properties":{"id":{"type":"string","example":"TXN-20220602695615","description":"ID of the Event assigned to the incoming dispute"},"type":{"type":"string","example":"DISPUTE","description":"The type of the Event","enum":["RETRIEVAL_REQUEST","DISPUTE","DISPUTE_SECOND","REPRESENTMENT","FEE_COLLECTION","TRANSFER_TO_MERCHANT","TRANSFER_TO_ACQUIRER","REVERSE_TRANSFER","VISA_ALLOCATION_PREARBITRATION","VISA_ALLOCATION_PREARBITRATION_RESPONSE","VISA_ALLOCATION_ARBITRATION","VISA_ALLOCATION_ARBITRATION_RESPONSE","DISPUTE_CREDIT","DISPUTE_RESPONSE","VISA_COLLABORATION_PREARBITRATION","VISA_COLLABORATION_PREARBITRATION_RESPONSE","VISA_COLLABORATION_ARBITRATION","VISA_COLLABORATION_ARBITRATION_RESPONSE","VISA_PRECOMPLIANCE","VISA_COMPLIANCE","VISA_PRECOMPLIANCE_RESPONSE","VISA_COMPLIANCE_RESPONSE","MASTERCARD_PREARBITRATION","MASTERCARD_PRECOMPLIANCE","MASTERCARD_ARBITRATION","MASTERCARD_COMPLIANCE"]},"longDescription":{"type":"string","example":"Dispute","description":"Event Long Description."},"reversal":{"type":"boolean","description":"Is this a reversal of a previous item?","example":false},"partial":{"type":"boolean","description":"Is this a partial dispute item?","example":false},"received":{"type":"string","format":"date","description":"The date this event was received","example":"2022-06-02"},"networkSettlementAmount":{"$ref":"#/components/schemas/Amount"},"networkSettlementCurrency":{"$ref":"#/components/schemas/Currency-Code"},"merchantFundingAmount":{"$ref":"#/components/schemas/Amount"},"merchantFundingCurrency":{"$ref":"#/components/schemas/Currency-Code"},"visaIssuerResponse":{"type":"string","description":"Notes provided for a partial or full decline from the Issuer (Visa only).","enum":["FULL","PART","DECL"],"example":"FULL"},"issuerReason":{"type":"string","description":"Reason provided for a partial or full decline from the Issuer","minLength":1,"maxLength":10000,"example":"The cardholder MR D HOLLIDAY reaffirms that he did not participate and he did not authorise the transaction"},"visaPreArbResponse":{"type":"string","description":"Visa's response to a Pre-Arbitration.","example":"FULL","enum":["FULL","PART","DECL"]},"allowedActions":{"type":"array","description":"List of actions you are allowed to perform against this event including directions on how to perform it with required data fields","items":{"$ref":"#/components/schemas/Action"}},"previousActions":{"type":"array","description":"List of actions that have previously been performed against this event","items":{"$ref":"#/components/schemas/Action-Simple"}}}},{"$ref":"#/components/schemas/Reason-Code-Description"}]},"Action":{"title":"Action","type":"object","description":"An action that can be performed against a dispute","properties":{"code":{"$ref":"#/components/schemas/Action-Code"},"description":{"type":"string","description":"Description of the action that can be performed","example":"Accept","minLength":1,"maxLength":255},"extendedDescription":{"type":"string","description":"Extended Description for the action","example":"Merchant accepts the dispute at the Visa Allocation Pre-Arbitration stage"},"status":{"$ref":"#/components/schemas/Action-Status"},"requiredDataFields":{"type":"array","description":"List of the fields that are required when performing this action","items":{"$ref":"#/components/schemas/Action-Fields"}}},"required":["code","description","requiredDataFields"]},"Document":{"title":"Document","type":"object","properties":{"id":{"type":"string","example":"20220627739641","description":"Document ID of the document uploaded for dispute"},"description":{"type":"string","description":"Category description for the document","enum":["ACKNOWLEDGEMENT","ARBITRATION","ARBITRATION_RESPONSE","COMPLIANCE","DISPUTE","DISPUTE_ACCEPT","DISPUTE_CBK2","DISPUTE_RESPONSE","FILING_RESPONSE","FINAL_DECISION","FULFILLMENT","NOT_APPLICABLE","NON_FULFILLMENT","PREARBITRATION","PREARBITRATION_RESPONSE","PRECOMPLIANCE","PRECOMPLIANCE_RESPONSE","REPRESENTMENT","RETRIEVAL","ARBITRATION_WITHDRAWAL","COMPLIANCE_WITHDRAWAL","VCR_ARBITRATION_SPLIT","VCR_ARBITRATION_WON","VCR_ARBITRATION_LOST","VCR_COMPLIANCE_SPLIT","VCR_COMPLIANCE_WON","VCR_COMPLIANCE_LOST"],"example":"PREARBITRATION"},"filename":{"type":"string","example":"image.tiff","description":"The file name of the document"},"filetype":{"type":"string","description":"The type of the document","enum":["DOCX","JPEG","PDF","TEXT","BITMAP","XML","GIF","JPG","DOC","TIF","DAT","TIFF"],"example":"TIFF"},"status":{"type":"string","description":"Status of the document in relation to the card scheme","enum":["PENDING_SEND","RECEIVED","ORIGINAL_PDF"],"example":"RECEIVED"},"uploadedBy":{"type":"string","example":"API_USER","description":"Who uploaded the Document"},"uploaded":{"type":"string","format":"date-time","description":"When the document was uploaded"},"errorMessage":{"type":"string","description":"Error message based on the response from scheme if the acquirer action has failed.","example":"Currency - Provided GBP value is not valid"}}},"Note":{"title":"Dispute-Note","type":"object","description":"A note added to a dispute either by an acquirier or merchant to provide additional information and detail.","properties":{"id":{"type":"integer","format":"int64","minimum":19000101000000,"maximum":99991231999999,"example":20240124123456,"description":"Unique ID generated for the note added."},"tcn":{"type":"string","description":"Unique Transaction Control Number generated for the note added.","example":"-943823606"},"content":{"type":"string","example":"Oh what a lovely note!","minLength":1,"maxLength":4000,"pattern":"^(?!\\s*$).+","description":"The note content itself."},"createdBy":{"type":"string","minimum":1,"maximum":100,"example":"Any name","description":"The name of the Application that created the note."},"created":{"type":"string","format":"date-time","example":"2024-01-13T09:12:28+01:00","description":"The date and time the note was created in ISO 8601 format."},"updatedBy":{"maximum":100,"minimum":1,"type":"string","description":"The name of the Application that updated the note.","example":"Any Name"},"updated":{"type":"string","description":"The date and time the note was updated in ISO 8601 format.","format":"date-time","example":"2024-01-13T08:12:28.000Z"},"userName":{"maxLength":50,"minLength":1,"pattern":"^(?!\\s*$).+","type":"string","description":"User name of the individual who added the notes.","example":"Alan"}},"x-examples":{}},"Error":{"description":"This is the generic Error Response to be used for all Errors sent back in responses.","type":"object","title":"Error Response","properties":{"errors":{"type":"array","uniqueItems":false,"items":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","description":"Readable error message that could be displayed in a UI"},"detail":{"type":"string","description":"Further description provided to give wider context into the error"},"source":{"type":"string","description":"Optional: Known source of error such as missing or invalid field in a request"}},"required":["title","detail"]}}},"required":["errors"]},"Action-Fields":{"title":"Action-Fields","type":"object","description":"","properties":{"name":{"type":"string","description":"Field name to use in the actions request","example":"evidence"},"description":{"type":"string","description":"Description of the field","example":"Evidence such as photographs or emails, to prove a link between the person receiving the merchandise or services and the cardholder, or to prove that the cardholder disputing the transaction is in possession of the merchandise and/or is using the services. We support files formatted as TIFF, PDF, DOCX and DOC"},"notes":{"type":"string","example":"This is a string with a minimum length of 0 and a maximum length of 10000","description":"Any extra notes to explain the usage of this data inside the disputes process"},"type":{"type":"string","example":"string","description":"A valid OpenAPI field type"},"format":{"type":"string","description":"A valid OpenAPI field format","example":"binary"},"example":{"type":"string","example":"I am declining this dispute because i have already refunded the cardholder","description":"An example value to indicate how this field can be used when taking action on a dispute"},"required":{"type":"string","description":"Whether this field is required or not","example":"Y","enum":["Y","N","YC","NC"]},"condition":{"type":"string","description":"condition when required is either YC or NC."},"minLength":{"type":"number","description":"Minimum length of the field"},"maxLength":{"type":"number","description":"Maximum length of the field"},"pattern":{"type":"string","description":"Regex pattern used to validate the field"}},"required":["name","description","type","format"]},"Action-Simple":{"title":"Action-Simple","type":"object","description":"An action that can be performed against a dispute. Used in summaries and lists.","properties":{"id":{"$ref":"#/components/schemas/Action-Id"},"code":{"$ref":"#/components/schemas/Action-Code"},"description":{"type":"string","description":"Description of the action that can be performed","example":"Accept","minLength":1,"maxLength":255},"extendedDescription":{"type":"string","description":"Extended Description for the action","example":"Merchant accepts the dispute at the Visa Allocation Pre-Arbitration stage"},"status":{"$ref":"#/components/schemas/Action-Status"},"modified":{"type":"string","format":"date-time","description":"Date and Time the Action was last modified","example":"2019-08-24T14:15:22Z"},"modifiedBy":{"type":"string","description":"User that last modified the action","example":"Bob"},"errorMessage":{"type":"string","description":"Error message based on the response from scheme if the acquirer action has failed.","example":"Currency - Provided GBP value is not valid"}},"required":["id","description","status"]},"Action-Status":{"title":"Action-Status","type":"string","example":"AVAILABLE","description":"Current status of the action","enum":["AVAILABLE","ACCEPTED","SUBMITTED","PROCESSED","ERROR","UNDONE"]},"Condition-Code":{"title":"Condition-Code","type":"string","description":"The code that represents the sub category of the dispute reason code within the card scheme.","example":"1"},"Condition-Description":{"title":"Condition-Description","type":"string","description":"The description for the subcategory code of dispute condition.","example":"EMV Liability Shift Counterfeit Fraud"},"Due":{"title":"Due","type":"string","format":"date","description":"Date the Dispute is due for reply. Penalties are likely to be incurred after this date or the dispute will be automatically forfeited."},"workByDate":{"type":"string","format":"date","description":"Indicates the last date when the merchant can take action on the chargeback, formatted as YYYY-MM-DD. The workByDate is calculated for the merchant's reference based on the acquirer's configuration. The acquirer reserves a few days from the overall due date and provides the remaining days for merchants to review and act, allowing the acquirer to assess the merchant's action and make a final decision accordingly.","example":"2019-08-24"},"Dispute-Id":{"type":"string","description":"Dispute ID","example":"20220602835125"},"Last-Action":{"title":"Last Action","type":"string","format":"date-time","description":"Date the last action was taken on this dispute"},"Mastercard-Id":{"type":"string","title":"Mastercard ID","description":"Mastercard assigned ID. This is the unique identifier given by Mastercard's disputes handling system","minLength":0,"maxLength":19,"example":"6549873216549876545"},"Note-Create":{"title":"Note-Create","type":"object","description":"Creating a new note","properties":{"tcn":{"$ref":"#/components/schemas/Tcn"},"content":{"type":"string","minLength":1,"maxLength":4000,"example":"Oh what a lovely note!","pattern":"^(?!\\s*$).+","description":"The note content itself."},"userName":{"type":"string","example":"Alan","minLength":1,"maxLength":50,"pattern":"^(?!\\s*$).+","description":"User name of the individual who adds the notes."}},"required":["tcn","content"]},"Dispute-Note-Response":{"title":"Dispute-Note-Response","type":"object","description":"Details of the note added to a dispute.","properties":{"id":{"type":"integer","format":"int64","minimum":19000101000000,"maximum":99991231999999,"example":20240124123456,"description":"Unique ID generated for the note added."},"tcn":{"type":"string","description":"Unique Transaction Control Number generated for the note added.","example":"-943823606"},"createdBy":{"type":"string","minimum":1,"maximum":100,"example":"Any name","description":"The name of the Application or user that created the note."},"created":{"type":"string","format":"date-time","example":"2024-01-13T09:12:28+01:00","description":"The date and time the note was created in ISO 8601 format."},"userName":{"maxLength":50,"minLength":1,"pattern":"^(?!\\s*$).+","type":"string","description":"User name of the individual who added the notes.","example":"Alan"}}},"Add-Document-Response":{"title":"Add-Document-Response","type":"object","description":"Unique document id generated for the document attached to the chargeback case.","properties":{"documentId":{"type":"integer","format":"int64","example":20210720958791,"minimum":19000101000000,"maximum":99991231999999,"description":"Unique identifier of the document uploaded for dispute."}}},"TemplateCategoryCode":{"type":"string","pattern":"^[0-9]{3,3}$","title":"templateCategoryCode","description":"The category of the letter template/attachment attached to the chargeback case.","maxLength":3,"minLength":3,"example":"006"},"DocumentNote":{"type":"string","pattern":"^[\\p{L}\\d\\s\\.\\,\\;\\'\\-\\\"\\“\\„&\\(\\)\\[\\]\\{\\}\\:\\!\\?<>]{0,2000}$","description":"Additional internal notes for the attachment purpose.","minLength":0,"maxLength":2000,"example":"Any document note"},"Posted":{"title":"Posted","type":"string","format":"date","description":"Date the Dispute was posted from the card scheme"},"Reason-Code":{"title":"Reason-Code","type":"string","example":"10","description":"Code provided by the card scheme providing the reason as to why the dispute has been raised"},"Reason-Description":{"title":"Reason-Description","type":"string","example":"CBK: Fraud","description":"Description provided by the card scheme providing the reason as to why the dispute has been raised"},"Result":{"title":"Result","type":"string","description":"The result of this dispute. Only available once the case is closed","example":"WON","enum":["WON","LOST","LETTER","SPLIT"],"nullable":true},"Scheme":{"type":"string","title":"Scheme","example":"VISA","enum":["VISA","MASTERCARD","JCB"],"description":"The card scheme that this dispute relates to"},"Stage-Description":{"title":"Stage-Description","type":"string","example":"Dispute","description":"Description of the current Dispute Stage"},"Stage":{"type":"string","title":"Stage","enum":["RRQ","CBK1","CBK2","FFR","NFF","REP","DRESP","CBKA","APARB","APARBR","APARBA","CPARB","CPARBR","AARB","AARBR","CARB","CARBR","PCOMPL","PCOMPLR","COMPL","COMPLR","RRQE","CBK1E","CBK2E","APARBRE","CPARBE","CARBE","PCOMPLE","COMPLE","MCMPARB","MCMARB","MCMPCOMP","MCMCOMP","MCMPARBR","MCMARBR","MCMPCOMPR","MCMCOMPR","RDR"],"description":"The specific stage that this dispute is in\n\n**Examples:**\n\n| Code | Description       |\n| ---  | ---               |\n| RRQ  | Retrieval Request |\n| CBK1 | Dispute           |\n| CBK2 | Dispute (2nd CBK) |\n| FFR  | Fulfillment       |\n| NFF  | Nonfulfillment    |\n| REP  | Representment     |\n\nFor a **full list** of stage code descriptions, please see the [disputes stages guide](https://docs.fiserv.dev/public/docs/dispute-stages).","example":"CBK1"},"Status":{"title":"Status","type":"string","example":"OPEN","enum":["OPEN","IN_PROGRESS","CLOSED"],"description":"Open = Action Required, In Progress = Action has been taken and waiting on further processing, Closed = Dispute cannot be processed any further"},"Visa-Id":{"title":"Visa-Id","description":"Visa assigned ID. This is the unique identifier given by Visa's disputes handling system","type":"string","pattern":"^[0-9]{0,20}$","minLength":0,"maxLength":20,"example":"65498732165498765455"},"Currency-Code":{"type":"string","title":"Currency Code","description":"[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.","minLength":3,"maxLength":3,"example":"EUR","pattern":"^[A-Za-z]{3}$"},"Arn":{"type":"string","title":"Acquirer Reference Number","description":"Acquirer Reference Number is a unique number that tags a credit or debit card transaction when it goes from the merchant’s bank through to the cardholder’s bank.","example":"74720942152221525432246","pattern":"^[0-9]{23,24}$","minLength":23,"maxLength":24},"Merchant-Id":{"title":"Merchant-Id","type":"string","pattern":"^[0-9]{0,20}$","description":"Merchant ID","minLength":0,"maxLength":20,"example":"87654567654898732154"},"Merchant-Transaction-Ref":{"title":"Merchant-Transaction-Ref","type":"string","pattern":"^[a-zA-Z0-9À-ý_ \\.\\&\\,\\-]{0,23}$","description":"Merchant's original transaction reference","minLength":0,"maxLength":23,"example":"POSI0709080000"},"Card-Issuer":{"title":"Card Issuer","description":"Name of the card issuing organization","type":"string","pattern":"^[A-Za-z0-9.-_ :]{0,32}$","minLength":0,"maxLength":32,"example":"RBS"},"Authorisation":{"title":"Authorisation","type":"object","properties":{"id":{"type":"string","description":"Authorisation ID","example":"1234567890123456789012"},"date":{"type":"string","format":"date-time","description":"Date of the authorisation"},"authCode":{"$ref":"#/components/schemas/Auth-Code"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency-Code"},"posEntryMode":{"type":"string","description":"Point of service entry mode as a 3 digit value. Corresponds to ISO 8583 field 22. PAN entry mode, the first 2 digits. PIN entry capability, the third digit.","example":"071"},"eciSli":{"type":"string","description":"MasterCard's SLI (Security Level Indicator) or Visa's ECI (Electronic Commerce Indicator)","pattern":"^[0-9]{0,2}$","minLength":2,"maxLength":2,"example":"05"},"ucaf":{"type":"string","description":"Mastercard’s Universal Cardholder Authentication Field. It refers to information collected in online transactions, specifically relating to Mastercard’s “SecureCode” program.","pattern":"^[0-9]$","minLength":0,"maxLength":1,"example":"0"}}},"Auth-Code":{"title":"Auth-Code","type":"string","pattern":"^[0-9]{1,6}$","description":"Six characters auth code for the authorisation","minLength":1,"maxLength":6,"example":"450213"},"Reason-Code-Description":{"title":"Reason-Code-Description","type":"object","properties":{"reasonCode":{"$ref":"#/components/schemas/Reason-Code"},"reasonDescription":{"$ref":"#/components/schemas/Reason-Description"},"visaConditionCode":{"$ref":"#/components/schemas/Condition-Code"},"visaConditionDescription":{"$ref":"#/components/schemas/Condition-Description"}}},"Action-Code":{"type":"string","title":"Action-Code","description":"Code representing the action that is to be performed","example":86},"Action-Id":{"type":"integer","format":"int64","minimum":19000101000000,"maximum":99999999999999,"example":20130121766544,"title":"Action-Id","description":"Action ID"},"Tcn":{"type":"string","example":"-943823606","title":"Tcn","description":"Transaction Control Number (used to control concurrent actions and avoid change clashes)"},"Amount":{"type":"number","title":"Amount","description":"The amount of currency in ISO 4217 format (to 2 decimal places).","example":20.99}},"securitySchemes":{"Api-Key":{"name":"Api-Key","type":"apiKey","in":"header","description":"Your API key from the Developer Platform"}},"parameters":{"disputeId":{"name":"disputeId","in":"path","schema":{"type":"string","example":"20220602835125","minLength":19000101000000,"maxLength":99991231999999},"description":"Unique case identifier assigned to the dispute","required":true},"documentId":{"name":"documentId","in":"path","schema":{"type":"integer","format":"int64","example":20220809748122,"minimum":19000101000000,"maximum":99991231999999},"description":"Unique identifier of the document uploaded for dispute.","required":true},"noteId":{"name":"noteId","in":"path","required":true,"schema":{"type":"string","example":"20220721948337"},"description":"Unique ID for the Note"},"eventId":{"name":"eventId","in":"path","required":true,"schema":{"type":"string","example":"TXN-20220602695615"},"description":"Unique identifier assigned to the incoming dispute Event i.e. Transaction or Document Event."},"actionId":{"name":"actionId","in":"path","required":true,"schema":{"type":"string","minimum":19000101000000,"maximum":99999999999999,"example":"20130121766544"},"description":"Unique identifier assigned to the action taken on the dispute."},"stage":{"name":"stage","in":"query","required":false,"schema":{"type":"array","items":{"example":"RRQ,CBK1","enum":["RRQ","FFR","NFF","CBK1","REP","DRESP","CBKA","APARB","APARBR","APARBA","CPARB","CPARBR","CBK2","AARB","AARBR","CARB","CARBR","PCOMPL","PCOMPLR","COMPL","COMPLR","RRQE","CBK1E","CBK2E","APARBRE","CPARBE","CARBE","PCOMPLE","COMPLE","MCMPARB","MCMARB","MCMPCOMP","MCMCOMP","MCMPARBR","MCMARBR","MCMPCOMPR","MCMCOMPR","RDR"]}},"description":"Filter Disputes by stage. For a **full list** of stage code descriptions, please see the [disputes stages guide](https://docs.fiserv.dev/public/docs/dispute-stages)"},"Message-Signature":{"name":"Message-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"Optional security header. Used to ensure the request has not been tampered with during transmission. The Message-Signature is the Base64 encoded HMAC hash (SHA256 algorithm with the API Secret as the key.) For more information, refer to the supporting documentation on the Developer Portal."},"Institution-Number":{"name":"Institution-Number","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":8},"description":"Institution number (8-digit number) associated with the merchant. This information defines the acquirer for the merchant. If a consumer is granted access to this API for multiple institutions, this field must be populated. If access is for only one institution, the API will automatically determine this value, making it optional for the client."}},"responses":{"AccessForbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Forbidden":{"value":{"errors":[{"title":"Forbidden error","detail":"Access to the requested resource is forbidden."}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"AuthenticationError":{"description":"Unauthorised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Unauthorised":{"value":{"errors":[{"title":"Authentication Error","detail":"No valid API key or credential has been provided in the request."}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Internal server error":{"value":{"errors":[{"title":"Internal Server Error","detail":"Sorry, something has gone wrong at our end. If this persists please contact support and provide the value of your Trace-Id header."}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"ResourceNotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Not found":{"value":{"errors":[{"title":"Resource Not Found","detail":"The requested resource cannot be found."}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Bad request":{"value":{"errors":[{"title":"Bad Request - Incorrect or Missing Field","detail":"There is a validation error with fieldName. Field in body is mandatory. Please fix and repeat your request.","source":"fieldName"}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}},"TooManyRequests":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"Too many requests":{"value":{"errors":[{"title":"Too many requests","detail":"Too many requests have been received too quickly. Please back off your requests and try again."}]}}}}},"headers":{"Trace-Id":{"schema":{"type":"string"},"description":"An internal unique ID for this request which can be used for diagnosing issues and corresponding with support."}}}}},"security":[{"Api-Key":[]}],"x-author":"Sandro Felipe","tags":[{"name":"Endpoints"}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}