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:

Format for GET /entities/{entity-id}/disputes Request URL

GET /entities/{entity-id}/disputes?from_date={fromDate}&to_date={toDate}&response_date_sort={dateType}&retrieve_images={includeImages}

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 following query string parameter:

Format for GET entities/{entity-id}/disputes/{dispute-id} Request URL

GET /entities/{entity-id}/disputes/{dispute-id}?retrieve_images={includeImages}

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

GET /entities/3ede43b4-8a1a-4bc9-a120-f07836ddf7d9/disputes/FRI3dJoEHQ/f8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Llc?retrieve_images=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/{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 one or more files, the merchant sends a POST request to /entities/{entity-id}/files.

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

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

The response includes files.correlationId. Use this correlationId when performing an action on the dispute, the second step of the representment flow.

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

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

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": [
    "IZI3dJoEHQ/f8gaGUi86So4F8AQiznNgxWZFLvDJVxhBU3tq0kzakLH6wWpM+Llc"
  ]
}

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.