# notifyDispute

> This API is used by Antom to send the dispute information to the merchant.

This API is used by Antom to send the dispute information to the merchant. 

# Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **Note**: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
>
> -   If the data type of a field is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a field is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### paymentRequestId (String, REQUIRED)

The unique ID that is assigned by a merchant to identify a payment request.

More information:

- Maximum length: 64 characters

#### disputeId (String, REQUIRED)

The unique ID that is assigned by Antom to identify a dispute.

More information:

- Maximum length: 64 characters

#### paymentId (String, REQUIRED)

The unique ID that is assigned by Antom to identify a payment.

More information:

- Maximum length: 64 characters

#### disputeTime (Datetime)

The date and time when the dispute is created.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### disputeAmount (Amount)

The amount of the transaction which has a dispute.

> Note: This parameter is returned when a dispute occurs.

##### currency (String, REQUIRED)

The transaction currency, which is a 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency).

For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe).

More information:

- Value range: 0 - unlimited

#### disputeNotificationType (String, REQUIRED)

The type of dispute notification. Valid values are:

-   `DISPUTE_CREATED`: indicates that a dispute occurs.
-   `DISPUTE_JUDGED`: indicates that the dispute is judged.  
-   `DISPUTE_CANCELLED`: indicates that the dispute is cancelled by the user.  
-   `DEFENSE_SUPPLIED`: indicates that your defense documents for the dispute are submitted.
-   `DEFENSE_DUE_ALERT`: a warning sent by Alipay that notifies your defense is to be overdue within 24 hours of _defens__eDueTime_.
-   `DISPUTE_ACCEPTED`: indicates that a dispute is accepted.
-   `RDR_RESOLVED` : indicates that the dispute is an RDR (Rapid Dispute Resolution) type.

More information:

- Maximum length: 30 characters

#### disputeReasonMsg (String)

The dispute reason.

More information:

- Maximum length: 256 characters

#### disputeJudgedTime (Datetime)

The date and time when the dispute is judged.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### disputeJudgedAmount (Amount)

The deduction amount of the dispute.

> Note: This parameter is returned when a dispute is judged.

##### currency (String, REQUIRED)

The transaction currency, which is a 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency).

For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe).

More information:

- Value range: 0 - unlimited

#### disputeJudgedResult (String)

The result of the dispute judgement. Valid values are: 

-   `ACCEPT_BY_CUSTOMER`: indicates that the dispute is judged to be the buyer's responsibility. Antom unfreezes the captured funds and you can handle the funds freely.
-   `ACCEPT_BY_MERCHANT`: indicates that the dispute is judged to be the merchant's responsibility. Antom unfreezes the captured funds but deduct from your settlement account to refund the buyer. 
-   `VALIDATE_SUCCESS`: Indicates that the compliance request materials were successfully validated after being uploaded.  
-   `VALIDATE_FAIL`: indicates that the compliance request materials failed validation after being uploaded.

More information:

- Maximum length: 30 characters

#### defenseDueTime (Datetime)

The due time after which you cannot defend the dispute.

> Note: This parameter is returned when the value of _disputeNotificationType_ is `DISPUTE_CREATED` or `DEFENSE_DUE_ALERT`.

#### disputeReasonCode (String)

The reason code indicating why a payment is disputed. For details about the reason codes, see [Chargeback reason codes](https://docs.antom.com/ac/dispute/reason_code.md).

> Note: This parameter is returned when the value of _disputeNotificationType_ is `DISPUTE_CREATED` or `DISPUTE_JUDGED`.

More information:

- Maximum length: 64 characters

#### disputeSource (String)

The card scheme that is responsible for processing the dispute.

> Note: This parameter is returned when the value of _disputeNotificationType_ is `DISPUTE_CREATED` or `DISPUTE_JUDGED`.

More information:

- Maximum length: 64 characters

#### arn (String)

Acquirer reference number (ARN) of the dispute.

> Note: This parameter is returned when the value of _disputeNotificationType_ is `DISPUTE_CREATED`.

More information:

- Maximum length: 64 characters

#### disputeAcceptReason (String)

Reasons for accepting disputes. Specify this parameter when the value of _disputeNotificationType_ is `DISPUTE_ACCEPTED`. Valid values are:

-   `MERCHANT_ACCEPTED`: indicates acceptance of the dispute initiated by the merchant.
-   `TIMEOUT`: indicates acceptance of the dispute due to a timeout scenario, wherein if the merchant fails to defend the dispute within the designated timeframe, the dispute will be automatically accepted.
-   `MANUAL_PROCESSING_ACCEPTED`: indicates acceptance of the dispute due to the manual processing.

#### disputeAcceptTime (Datetime)

The time when the dispute is accepted.

> Note: Specify this parameter when the value of _disputeNotificationType_ is `DISPUTE_ACCEPTED`.

#### disputeType (String, REQUIRED)

The dispute type. The valid values includes:

-   `CHARGEBACK`: indicates that the dispute type is chargeback.
-   `RETRIEVAL_REQUEST`：indicates that the dispute type is retrieval request.
-   `COMPLIANCE_REQUEST`：indicates that the dispute type is compliance request.

More information:

- Maximum length: 64 characters

#### defendable (Boolean)

Indicates whether the dispute is defendable. Valid values are:

-   `true`: Indicates the dispute is defendable and this chargeback will need you to handle it.
-   `false`: Indicates the dispute is not defendable and this chargeback will be handled by Antom subsequently.

#### captureId (String)

The unique ID that is assigned by Antom to identify a capture.

> **Note:** Specify this field to associate with the corresponding chargeback notice request if there are mutiple capture request.

More information:

- Maximum length: 64 characters

#### autoDefendReason (String)

The automatic defense reason.

> **Note**: This parameter is only applicable when the value of defendable is false and a chargeback occurs.

More information:

- Maximum length: 256 characters

## Response parameters

#### result (Result, REQUIRED)

A fixed value, which is sent to Antom to acknowledge that the notification is received.

##### resultCode (String, REQUIRED)

The result code. The value is fixed as `SUCCESS`.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

The result status. The value is fixed as `S`, which means the notification is received successfully.

##### resultMessage (String, REQUIRED)

The result message that explains the result code. The value is fixed as `success`.

More information:

- Maximum length: 256 characters

## Result process logic

Send the following message with fixed values to Antom after receiving the notification, to acknowledge that the notification from Antom is received:

```json
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}
```

If no such message is returned to Antom due to operation issues or network issues, Antom will intermittently send the notification until the required message is returned by the merchant. Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to eight times, with an interval of 0s, 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

> **Note**: In the sandbox environment, if you do not return information in the specified format, Antom will not resend asynchronous notifications to you.

## Result/Error codes

| Code | Value | Message |
| --- | --- | --- |
| SUCCESS | S | Success |

## Request

### DISPUTE_CREATED

```json
{
  "disputeAmount": {
    "currency": "EUR",
    "value": "1000"
  },
  "disputeId": "202209212501310115730104****",
  "disputeNotificationType": "DISPUTE_CREATED",
  "defenseDueTime": "2023-09-20T23:41:32-07:00",
  "disputeTime": "2022-09-20T23:41:32-07:00",
  "disputeReasonCode": "4853",
  "disputeReasonMsg": "Other Fraud",
  "disputeSource": "Mastercard",
  "paymentId": "202209231540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "disputeType": "CHARGEBACK"
}
```

### DISPUTE_JUDGED

```json
{
  "disputeId": "202209232501310182580105****",
  "disputeJudgedAmount": {
    "currency": "USD",
    "value": "185"
  },
  "disputeJudgedResult": "ACCEPT_BY_MERCHANT",
  "disputeJudgedTime": "2022-09-23T01:16:42-07:00",
  "disputeNotificationType": "DISPUTE_JUDGED",
  "disputeReasonMsg": "Late Presentment",
  "disputeReasonCode": "4853",
  "disputeSource": "Mastercard",
  "paymentId": "202209231540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "disputeType": "CHARGEBACK"
}
```

### DISPUTE_CANCELLED

```json
{
  "defendable": false,
  "disputeId": "2024120729013101750404751230",
  "disputeNotificationType": "DISPUTE_CANCELLED",
  "disputeType": "CHARGEBACK",
  "paymentId": "20241206194010900000188750264694763",
  "paymentRequestId": "202412061821002000000751750949"
}
```

### DEFENSE_SUPPLIED

```json
{
  "disputeId": "202209212501310115730104****",
  "disputeNotificationType": "DEFENSE_SUPPLIED",
  "disputeTime": "2022-09-20T23:41:32-07:00",
  "paymentId": "202209231540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "disputeType": "CHARGEBACK"
}
```

### DEFENSE_DUE_ALERT

```json
{
  "disputeId": "202401012501310115730104****",
  "disputeNotificationType": "DEFENSE_DUE_ALERT",
  "disputeTime": "2024-01-01T23:41:32-07:00",
  "defenseDueTime": "2024-01-03T23:41:32-07:00",
  "paymentId": "202401011540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "disputeType": "CHARGEBACK"
}
```

### DISPUTE_ACCEPTED

```json
{
  "disputeAmount": {
    "currency": "EUR",
    "value": "1000"
  },
  "disputeId": "202401012501310115730104****",
  "disputeNotificationType": "DISPUTE_ACCEPTED",
  "disputeAcceptTime": "2024-01-01T23:41:32-07:00",
  "disputeAcceptReason": "MERCHANT_ACCEPTED",
  "paymentId": "202401011540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "defendable": false
}
```

### RDR_RESOLVED

```json
{
  "disputeAmount": {
    "currency": "EUR",
    "value": "1000"
  },
  "disputeId": "202401012501310115730104****",
  "disputeNotificationType": "RDR_RESOLVED",
  "disputeTime": "2024-01-01T23:41:32-07:00",
  "paymentId": "202401011540108001001888XXXXXX****",
  "paymentRequestId": "requestId_12345****",
  "disputeReasonCode": "4853",
  "disputeSource": "Mastercard",
  "defendable": false
}
```

### DEFENSE_AUTOMATICALLY

```json
{
  "disputeAmount": {
    "currency": "EUR",
    "value": "1000"
  },
  "disputeId": "202209212501310115730104****",
  "disputeNotificationType": "DISPUTE_CREATED",
  "defenseDueTime": "2023-09-20T23:41:32-07:00",
  "disputeTime": "2022-09-20T23:41:32-07:00",
  "disputeReasonCode": "4853",
  "disputeSource": "Mastercard",
  "paymentId": "202209231540108001001888XXXXXX****",
  "captureId": "202412121940108070001886702096****",
  "defendable": "false",
  "autoDefendReason": "FULLY_REFUNDED",
  "paymentRequestId": "requestId_12345****"
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}
```