# initiateEscalation

The **initiateEscalation** API is used by Alipay+ to send an escalation initiation request to the Acquiring Service Provider. When using this API, the Acquiring Service Provider needs to take the following things into consideration:

-   Only Mobile Payment Providers (MPPs) can initiate an escalation.
-   For each transaction, a maximum of **2** escalations can be requested (excluding those that are canceled), while a transaction can have only **1** ongoing escalation.
-   Escalation request time limits:

-   Within **360** days after the original transaction, the MPP can initiate the first escalation;
-   Within **25** days after the first escalation is replied to or closed, the MPP can initiate the second escalation.

-   Escalation amount: The escalation amount cannot exceed the maximum available dispute amount.
-   Special Merchant: Currently this includes Apple and Google. They require additional information for escalation initiation. 

## 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](api_overview#3mLq0)
-   [Response header](api_overview#YdmVS)

**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

#### disputeRequestId (String, REQUIRED)

The unique ID that is assigned by Alipay+ to identify an escalation.

**Note:** If two requests specify the same value for _disputeRequestId_ but different values for _paymentRequestId_, the Acquiring Service Provider needs to return `REPEAT_REQ_INCONSISTENT` for the second request.

More information:

- This field is an API idempotency field.
- Maximum length: 64 characters

#### paymentRequestId (String, REQUIRED)

The unique ID that is assigned by Alipay+ to identify a payment where the escalation occurs.

More information:

- Maximum length: 64 characters

#### disputeOccurTime (Datetime, REQUIRED)

The date and time when the escalation occurs. For the Acquiring Service Provider, this parameter refers to the date and time when Alipay+ starts handling the escalation.

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".

#### disputeReasonCode (String, REQUIRED)

The code that reflects the dispute reason. Valid values are: 

-   `7801`: The code for merchandise-related reasons, which is used for an escalation.
-   `7802`: The code for transaction-processing-related reasons, which is used for an escalation.
-   `7803`: The code for fraud-related reasons, which is used for an escalation.

#### disputeReasonCodeDescription (String, REQUIRED)

The code that describes the dispute reason. Valid values are: 

-   `MERCHANDIZE_OR_SERVICE_NOT_RECEIVED`: specified if _reasonCode_ is `7801`, indicating that the merchandise/service is not received.
-   `NOT_AS_DESCRIBED`: specified if _reasonCode_ is `7801`, indicating that the merchandise/service is not as described.
-   `REFUND_NOT_PROCESSED`: specified if _reasonCode_ is `7801`, indicating that the refund is not processed.
-   `AMOUNT_DIFFER`: specified if _reasonCode_ is `7802`, indicating that there exists a difference between amounts.
-   `DUPLICATE_PROCESSED`: specified if _reasonCode_ is `7802`, indicating that the transaction is processed duplicately.
-   `PAIDED_BY_OTHER_MEANS`: specified if _reasonCode_ is `7802`, indicating that the transaction is paid by other means.
-   `USER_DENIED_PARTICIPANTING_IN_A_TRANSACTION`: specified if _reasonCode_ is `7803`, indicating that the user denied participating in the transaction.

#### escalationAmount (Amount, REQUIRED)

The escalation amount.

**Note:** The value of _escalationAmount.value_ cannot exceed the maximum available dispute amount.

##### currency (String, REQUIRED)

The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1.

More information:

- Value range: 1 - unlimited

#### merchantDisputeId (String)

The unique ID that is assigned by the merchant to identify an escalation.

**Note:** Specified by Alipay+ for transactions of Special Merchants.

More information:

- Maximum length: 32 characters

#### customerIdAssignedByMerchant (String)

The unique ID that is assigned by the merchant to identify a customer. 

**Note:** Specified by Alipay+ for the transactions of Special Merchants, with the exception of Apple and Google, where the value of this parameter is provided by the user.

More information:

- Maximum length: 32 characters

#### merchantNotRefundRecord (Array<Attachment>)

The list of supporting documents that are used to prove that the merchant does not refund.

**Note:** Specified by Alipay+ for the transactions of Special Merchants, with the exception of Apple and Google, where the documents are provided by the user.

##### attachmentType (String, REQUIRED)

The attachment type. Valid values are:

-   `ARTICLES_OF_ASSOCIATION`: indicates the articles of association.
-   `ENTERPRISES_ANNUAL_INSPECTION_REPORT`: indicates the enterprise annual inspection report.
-   `PROOF_OF_ADDRESS`: indicates the proof of address.
-   `OTHER_MATERIAL`: indicates other materials.
-   `REGISTRATION_CERTIFICATE`: indicates the registration certificate.
-   `TRANSACTION_RECEIPT`: indicates the transaction receipt.
-   `PROOF_OF_DELIVERY`: indicates the proof of delivery.
-   `MERCHANT_INFORMATION`: indicates the merchant information.
-   `END_USER_INFORMATION`: indicates the information of the end-user, also called the buyer.
-   `OTHER_DOCUMENTATION`: indicates other documents.
-   `MERCHANT_NOT_REFUND_RECORDS`: indicates the supporting documents that are used to prove that the merchant does not refund.
-   `SUPPORTING_DOCUMENTATION`: indicates the supporting documents.

##### file (String)

The attachment file.

**Note:** Required if _content_ is not specified.

More information:

- Maximum length: 1024 characters

##### attachmentName (String)

The name of the attachment.

More information:

- Maximum length: 128 characters

##### content (String)

The attachment content in Base64 format. 

**Note:** Required if _file_ is not specified.

More information:

- Maximum length: 2048000 characters

##### contentType (String)

The type of content format. Valid values are `pdf`, `doc`, `docx`, `xls`, `xlsx`, `bmp`, `jpg`, `jpeg`, `png`, and `gif`.

**Note:** Required if _content_ is specified.

More information:

- Maximum length: 8 characters

#### supportingDocumentation (Array<Attachment>)

The list of documents that are used to support the escalation.

##### attachmentType (String, REQUIRED)

The attachment type. Valid values are:

-   `ARTICLES_OF_ASSOCIATION`: indicates the articles of association.
-   `ENTERPRISES_ANNUAL_INSPECTION_REPORT`: indicates the enterprise annual inspection report.
-   `PROOF_OF_ADDRESS`: indicates the proof of address.
-   `OTHER_MATERIAL`: indicates other materials.
-   `REGISTRATION_CERTIFICATE`: indicates the registration certificate.
-   `TRANSACTION_RECEIPT`: indicates the transaction receipt.
-   `PROOF_OF_DELIVERY`: indicates the proof of delivery.
-   `MERCHANT_INFORMATION`: indicates the merchant information.
-   `END_USER_INFORMATION`: indicates the information of the end-user, also called the buyer.
-   `OTHER_DOCUMENTATION`: indicates other documents.
-   `MERCHANT_NOT_REFUND_RECORDS`: indicates the supporting documents that are used to prove that the merchant does not refund.
-   `SUPPORTING_DOCUMENTATION`: indicates the supporting documents.

##### file (String)

The attachment file.

**Note:** Required if _content_ is not specified.

More information:

- Maximum length: 1024 characters

##### attachmentName (String)

The name of the attachment.

More information:

- Maximum length: 128 characters

##### content (String)

The attachment content in Base64 format. 

**Note:** Required if _file_ is not specified.

More information:

- Maximum length: 2048000 characters

##### contentType (String)

The type of content format. Valid values are `pdf`, `doc`, `docx`, `xls`, `xlsx`, `bmp`, `jpg`, `jpeg`, `png`, and `gif`.

**Note:** Required if _content_ is specified.

More information:

- Maximum length: 8 characters

#### remarks (String)

Supplementary information.

**Note:** Specified by Alipay+ if there's any additional information that needs to be remarked.

More information:

- Maximum length: 1024 characters

## Response parameters

#### result (Result, REQUIRED)

The result of the business processing, including the result status, result code, and the result message.

##### resultCode (String, REQUIRED)

The result code that indicates the detailed processing result.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

The result status that indicates the processing result. Valid values are:

-   `S`: Successful
-   `F`: Failed
-   `U`: Unknown

##### resultMessage (String)

The result message that describes the result code in detail.

More information:

- Maximum length: 256 characters

#### disputeId (String)

The unique ID that is assigned by the Acquiring Service Provider to identify an escalation.

**Note:** Return this parameter if _result.resultStatus_ is `S`.

More information:

- Maximum length: 64 characters

## Result/Error codes

| Code | Value | Message |
| --- | --- | --- |
| SUCCESS | S | Success |
| ACCESS_DENIED | F | The escalation amount exceeds the transaction amount with no discount. |
| EXCEEDS_ESCALATION_REQUEST_LIMIT | F | The number limit of the escalation request for the transaction is exceeded. |
| EXCEEDS_ESCALATION_REQUEST_TIME_LIMIT | F | The time limit of the escalation request for the transaction is exceeded. |
| INVALID_CLIENT | F | The client is invalid.  |
| INVALID_SIGNATURE | F | The signature is invalid. |
| KEY_NOT_FOUND | F | The key is not found. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. |
| NO_INTERFACE_DEF | F | API is not defined. |
| ORDER_NOT_EXIST | F | The order doesn't exist. |
| PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. |
| SPECIAL_MERCHANT_REQUIRES_MERCHANT_CUSTOMER_ID | F | customerIdAssignedByMerchant is required of Special Merchants. |
| SPECIAL_MERCHANT_REQUIRES_MERCHANT_DISPUTE_ID | F | merchantDisputeId is required of Special Merchants. |
| SPECIAL_MERCHANT_REQUIRES_MERCHANT_NOT_REFUND_RECORD | F | merchantNotRefundRecord is required of Special Merchants. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
| UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. |

## Request

### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT

```json
{
  "disputeRequestId": "201811291907410200070000000000",
  "paymentRequestId": "202111291907410200070000000000",
  "disputeOccurTime": "2020-10-10T12:01:01+08:30",
  "disputeReasonCode": "7801",
  "disputeReasonCodeDescription": "MERCHANDIZE_OR_SERVICE_NOT_RECEIVED",
  "escalationAmount": {
    "currency": "HKD",
    "value": "100"
  },
  "remarks": "remark"
}
```

## Response

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