Overview

To automate dispute handling, merchants use the REST 2.0 Disputes API:

The Disputes API currently supports Visa and Mastercard disputes for which Nuvei is the direct acquirer. Future releases will provide additional support.

Retrieve a List of Disputes

To retrieve a list of disputes for a processing entity, the merchant sends a GET request to /entities/{entity-id}/disputes, using the merchant’s processing entity ID provided by Nuvei. The merchant can filter the list by including the following URL-encoded query string parameters in the request URL:

Example GET /entities/{entity-id}/disputes Request URL

GET /entities/3ede43b4-8a1a-4bc9-a120-f07836ddf7d9/disputes?from_date=2024-02-02&to_date=2024-02-06&response_date_sort=UpdateDate&retrieve_files=true

The response includes a status.code and a status.description for each dispute in the list. For a list of possible dispute status codes and descriptions, see below.

Example GET /entities/{entity-id}/disputes Response

{
  "totalResultCount": 1,
  "disputes": [
    {
      "id": "FRI3dJoEHQ/f8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Llc",
      "creationDate": "2022-09-02T11:38:26.511Z",
      "verdict": "",
      "transaction": {
        "id": 210000000,
        "date": "2022-08-02T11:38:26.511Z",
        "merchantTransactionId": "1324343",
        "arn": "1234556",
        "amount": 100.2,
        "currency": "USD"
      },
      "paymentOption": "Visa",
      "maskedCardNumber": "123456************3456",
      "availableActions": [
        "ACCEPT",
        "PARTIAL",
        "REJECT"
      ],
      "lastDisputeEvent": {
        "id": "ABI3dJoEHQ/f8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Mmc",
        "updateDate": "2022-09-04T11:38:26.511Z",
        "expirationDate": "2022-09-25T11:38:26.511Z",
        "status": {
          "code": "FC-M-RJCT",
          "description": "First Chargeback- Rejected by Merchant"
        },
        "disputeAmount": 100.2,
        "rejectAmount": 100.2,
        "currency": "USD",
        "remarks": "chargeback notes example",
        "disputeReason": {
          "code": "12.4",
          "description": "reason name"
        },
        "rejectReason": {
          "code": "IDRC25",
          "reason": "Invalid Dispute"
        },
        "files": [
          {
            "id": 123456,
            "name": "testimage.pdf",
            "data": "This is an image file stored in a base64 encoded string"
          }
        ],
        "initiatedBy": "Issuer"
      }
    }
  ]
}

Retrieve the Details of a Dispute

To retrieve the complete details for a dispute case, including the entire status flow, the merchant sends a GET request to entities/{entity-id}/disputes/{dispute-id}. The status flow indicates the stages the dispute went through until its current status. The request URL can include the query string parameter as described in Retrieve Dispute Details.

The response includes a status.code and a status.description for each dispute in the list. For a list of possible dispute status codes and descriptions, see below.

Example GET entities/{entity-id}/disputes/{dispute-id} Response

{
  "disputes": {
    "id": "FRI3dJoEHQ/f8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Llc",
    "creationDate": "2022-09-02T11:38:26.511Z",
    "verdict": "",
    "transaction": {
      "id": 210000000,
      "date": "2022-09-02T11:38:26.511Z",
      "merchantTransactionId": "1324343",
      "arn": "1234556",
      "amount": 100.2,
      "currency": "USD"
    },
    "paymentOption": "Visa",
    "maskedCardNumber": "123456************3456",
    "availableActions": [
      "ACCEPT",
      "PARTIAL",
      "REJECT"
    ],
    "disputeEvents": [
      {
        "updateDate": "2022-09-02T11:38:26.511Z",
        "expirationDate": "2022-09-02T11:38:26.511Z",
        "status": {
          "code": "FC",
          "description": "First Chargeback- Initiated by Issuer"
        },
        "disputeAmount": 100.2,
        "rejectAmount": null,
        "currency": "USD",
        "remarks": "chargeback notes example",
        "disputeReason": {
          "code": "12.4",
          "reason": "reason name"
        },
        "rejectReason": {
          "code": null,
          "description": null
        },
        "files": [
          {
            "id": 123456,
            "name": "testimage.pdf",
            "data": "This is an image file stored in a base64 encoded string"
          }
        ],
        "initiatedBy": "Issuer"
      },
      {
        "updateDate": "2022-09-02T11:38:26.511Z",
        "expirationDate": "2022-09-02T11:38:26.511Z",
        "status": {
          "code": "FC-M-RJCT",
          "description": "First Chargeback- Rejected by Merchant"
        },
        "disputeAmount": 100.2,
        "rejectAmount": 100.2,
        "currency": "USD",
        "remarks": "chargeback reject notes example",
        "disputeReason": {
          "code": "12.4",
          "reason": "reason name"
        },
        "rejectreason": {
          "code": "IDRC25",
          "descripion": "reason name"
        },
        "files": [
          {
            "id": 555456,
            "name": "respimage.pdf",
            "data": "This is a response image file stored in a base64 encoded string"
          }
        ],
        "initiatedBy": "Acquirer"
      }
    ]
  }
}

Upload Image Files

Merchants can re-present a dispute with supporting files. Uploading one or more files is the first step of the representment flow. To upload a file, the merchant sends a POST request to /entities/{entity-id}/files. In each request only one file can be uploaded.

The following is information related to the upload of parameters and an image file(s):

• files.name value is the file name of the image.
• files.data value is the base-64 encoded string of the file data.
• File size is in MB, with a maximum file size of 2 MB.
• Supported file format is PDF.

Example POST /entities/{entity-id}/files Request

{
"file":
{
"name": "testimage.pdf",
"data": "This is an image file stored in a base64 encoded string"
}
}

Example POST /entities/{entity-id}/files Response

{
"file":
{
"correlationId": "123e4567-e89b-12d3-a456-426655440000",
"name": "testimage.pdf"
},
"result": {
"status": "SUCCESS"
}
}

The final confirmation for a successful upload of a file is received via the callback (webhook) ‘Dispute API Image Callback‘. The callback includes a FileId, which is used if performing an action on the dispute (the second step of the representment flow).

Perform an Action on a Dispute

To submit a response to the dispute, the merchant sends a POST request to /entities/{entity-id}/disputes/{dispute-id}/{action}. The merchant can accept, partially accept, or reject the dispute. If the action requires a supporting file, the request must include the correlationID of the previously uploaded file.

Example POST /entities/{entity-id}/disputes/{dispute-id}/{action} Request URL

POST /entities/3ede43b4-8a1a-4bc9-a120-f07836ddf7d9/disputes/FRI3dJoEHf8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Llc/PARTIAL

Example POST /entities/{entity-id}/disputes/{dispute-id}/{action} Request

{
  "acceptedAmount": 100,
  "currency":"USD",
  "cardholderNoLongerDisputes": null,
  "notes": "the dispute was partial accepted because ...",
  "files": [
    "123e4567-e89b-12d3-a456-426655440000"
  ]
}

Example /entities/{entity-id}/disputes/{dispute-id}/{action} Response

{
  "disputeEventId": "55333abc422"
}

Dispute Status Codes

The following table lists the possible dispute status.codes and status.descriptions.