# responseEscalation

The **responseEscalation** API is used by Alipay+ to send the information that is related to an escalation to the Mobile Payment Provider (MPP), as a reply to the MPP's **initiateEscalation** request. 

## 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**:
>
> 1.  Set the data type of each parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
>
> -   If the data type of a parameter is Integer and its value is 20, set it as "20".
> -   If the data type of a parameter is Boolean and its value is `true`, set it as "true".
>
> 2.  For optional parameters that are not required in your case, you can take one of the following actions:
>
> -   Exclude the parameters from the request body.
> -   Set the parameter values as `null` (without the double quotation marks).
>
> Do NOT leave the optional parameters empty by setting their values as `""`; otherwise, an error might occur.

## 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_, Alipay+ returns `REPEAT_REQ_INCONSISTENT` for the second request.

More information:

- This field is an API idempotency field.For requests that are initiated with the same disputeRequestId, the MPP must regard the requests as repeated and process the requests only once.  The MPP is recommended to check the consistency of the refundType and refundAmount parameters. If either of their values is different from that in the previous request, Alipay+ returns the REPEAT_REQ_INCONSISTENT result code.
- Maximum length: 64 characters

#### refundType (String, REQUIRED)

The refund result that reflects whether the Acquiring Service Provider (ACQP) accepts the refund or not. Valid values are: 

-   `ACCEPT_REFUND`: indicates that the refund is accepted.
-   `ACCEPT_PARTIAL_REFUND`: indicates that the refund is partially accepted.
-   `REFUSE_REFUND`: indicates that the refund is refused.

#### refundAmount (Amount)

The amount that the ACQP agrees to refund. 

**Notes:**

-   Specified by Alipay+ if _refundType_ is `ACCEPT_PARTIAL_REFUND`.
-   When _refundType_ is `ACCEPT_REFUND`, the value of _refundAmount.value_ is by default the same as the value of _escalationAmount.value_ that is specified by the MPP in the **initiateEscalation** API.
-   The value of _refundAmount.value_ cannot exceed the value of _escalationAmount.value_ that is specified by Alipay+ in the **initiateEscalation** API.

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

#### plannedRefundTime (Datetime)

The date and time when the ACQP plans to process the refund.

**Note:** Specified by Alipay+ if _refundType_ is `ACCEPT_REFUND` or `ACCEPT_PARTIAL_REFUND` and the ACQP specifies this paramater in **responseEscalation** API.

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

#### transactionReceipt (TransactionReceipt)

The transaction receipt of the payment.

**Note:** Specified by Alipay+ if the ACQP has any transaction receipts of the payment.

##### referenceOrderId (String, REQUIRED)

The unique ID that is assigned by the merchant that directly provides services or goods for customers to identify an order. The ID is used to display the customer's purchase record and to track follow-up operations, such as customer complaints and disputes.

More information:

- Maximum length: 64 characters

##### orderAmount (Amount, REQUIRED)

The original order amount that is displayed by the merchant to the customer on the consumption records or payment result page.

**Note:** The value of _orderAmount.value_ can differ from the value of _paymentAmount.value_ for various reasons such as discounts.

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

##### goods (Array<Goods>, REQUIRED)

The goods information.

###### referenceGoodsId (String, REQUIRED)

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

More information:

- Maximum length: 64 characters

###### goodsName (String, REQUIRED)

The name of the goods.

More information:

- Maximum length: 256 characters

###### goodsCategory (String)

The categorization of the goods.

More information:

- Maximum length: 256 characters

###### goodsBrand (String)

The brand name of the goods.

More information:

- Maximum length: 32 characters

###### goodsUnitAmount (Amount)

The unit price of the goods.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

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

###### goodsQuantity (Integer)

The quantity of the goods. 

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Value range: 1 - unlimited

#### proofOfDelivery (ProofOfDelivery, REQUIRED)

The document that is used to prove that the purchased product or service has been delivered as agreed, which contains information such as the delivery tracking number and the shipping information.

**Note:** Specified by Alipay+ if the ACQP has any proof of delivery of the payment.

##### deliveryTrackingNo (String, REQUIRED)

The tracking number of the delivery.

More information:

- Maximum length: 128 characters

##### shipping (Shipping)

The shipping information.

###### shippingName (UserName, REQUIRED)

The name of the shipping recipient.

###### firstName (String)

The first name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### middleName (String)

The middle name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### lastName (String)

The last name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### fullName (String, REQUIRED)

The full name of the user.

More information:

- Maximum length: 128 characters

###### shippingAddress (Address, REQUIRED)

The shipping address.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name. 

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### shippingCarrier (String)

The name of the shipping carrier, such as FedEx, UPS, or USPS. 

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 128 characters

###### shippingPhoneNo (String)

The contact number of the shipping recipient.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 16 characters

#### merchantInformation (Merchant)

The merchant information.

**Note:** Specified by Alipay+ if the ACQP has any merchant information.

##### referenceMerchantId (String, REQUIRED)

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

More information:

- Maximum length: 64 characters

##### merchantMCC (String, REQUIRED)

The merchant category code (MCC) that represents the categorization of the merchant's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details.

More information:

- Maximum length: 32 characters

##### merchantName (String)

The legal name of the merchant.

More information:

- Maximum length: 256 characters

##### merchantAddress (Address)

In the Cashier Payment and Auto Debit scenarios, specify the region where the merchant is registered. In the User-presented Mode and Merchant-presented Mode Payment scenarios, specify the region where the payment transaction occurs.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name. 

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

##### merchantDisplayName (String)

The display name of the merchant.

**Note**: It is recommended that you specify this parameter if your display name is different from your legal name. The default value of this parameter is the value of the _merchantName_ parameter.

More information:

- Maximum length: 64 characters

##### merchantRegisterDate (Datetime)

The time when the merchant registered its business at the local regulatory agency.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

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

##### store (Store)

The information about the store of the merchant.

###### referenceStoreId (String, REQUIRED)

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

More information:

- Maximum length: 64 characters

###### storeName (String, REQUIRED)

The legal name of the store.

More information:

- Maximum length: 256 characters

###### storeMCC (String, REQUIRED)

The merchant category code (MCC) that represents the categorization of the store's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details.

More information:

- Maximum length: 32 characters

###### storeDisplayName (String)

The display name of the store.

**Note**: It is recommended that you specify this parameter if the display name of the store is different from its legal name.

More information:

- Maximum length: 64 characters

###### storeTerminalId (String)

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

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

###### storeOperatorId (String)

The unique ID that is assigned by the merchant to identify a cashier at the store.

More information:

- Maximum length: 64 characters

###### storePhoneNo (String)

The contact number of the store.

More information:

- Maximum length: 16 characters

###### storeAddress (Address)

The address where the store is located.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name. 

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

**Note**: Specify this parameter if you have the information. This provides better user experience.

More information:

- Maximum length: 32 characters

#### endUserInformation (Buyer)

The information of the end-user, also called the buyer.

**Note:** Specified by Alipay+ if the ACQP has any end-user information.

##### referenceBuyerId (String)

The unique ID that is assigned by the merchant or ACQP to identify a buyer.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

##### buyerName (UserName)

The name of the buyer.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

###### firstName (String)

The first name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### middleName (String)

The middle name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### lastName (String)

The last name of the user.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 32 characters

###### fullName (String, REQUIRED)

The full name of the user.

More information:

- Maximum length: 128 characters

##### buyerPhoneNo (String)

The contact number of the buyer.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 24 characters

##### buyerEmail (Email)

The email address of the buyer.

**Note**: Specify this parameter if you have the information. This helps anti-money laundering and fraud detection, and increases payment success rates.

More information:

- Maximum length: 64 characters

#### otherDocumentation (Array<Attachment>)

The list of any other documents.

**Note:** Specified by Alipay+ if the ACQP has any other documents.

##### 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: 2048 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

## More information

### How to return the result

For different business processing results at your side, return the result (specified on the _result_ parameter) by following the instructions below.

-   If the request is received successfully, set the value of _result.resultStatus_ to `S` and the value of _result.resultCode_ to `SUCCESS`.
-   If the request fails to be received, set the value of _result.resultStatus_ to `F` and specify the value of _result.resultCode_ according to the failure reason.

For more information about how to define your result codes, see the _Result codes_ section below.

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success |  |
| ACCESS_DENIED | F | Access is denied. |  |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. |  |
| EXCEEDS_ESCALATION_RESPONSE_TIME_LIMIT | F | The time limit of the escalation response for the transaction is exceeded. |  |
| INVALID_CLIENT | F | The client is invalid. |  |
| INVALID_SIGNATURE | F | The signature is invalid. |  |
| KEY_NOT_FOUND | F | The server does not implement the media type that is acceptable to the client. |  |
| METHOD_NOT_SUPPORTED | 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. |  |
| REFUND_AMOUNT_EXCEED_LIMIT | F | The refund amount exceeds the escalation amount. |  |
| 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

```json
{
  "disputeRequestId": "201811291907410200070000000000",
  "refundType": "ACCEPT_PARTIAL_REFUND",
  "refundAmount": {
    "currency": "JPY",
    "value": "500"
  },
  "plannedRefundTime": "2020-10-10T12:01:01+08:30",
  "transactionReceipt": {
    "referenceOrderId": "orderID_0101010000",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "goods": [
      {
        "referenceGoodsId": "orderID_0101010000",
        "goodsName": "goods",
        "goodsCategory": "category",
        "goodsBrand": "alipay",
        "goodsUnitAmount": {
          "value": "100",
          "currency": "JPY"
        },
        "goodsQuantity": "2"
      }
    ]
  },
  "proofOfDelivery": {
    "deliveryTrackingNo": "24210200070000000000",
    "shipping": {
      "shippingName": {
        "firstName": "Jay",
        "middleName": "Chou",
        "lastName": "Chou",
        "fullName": "Jay Chou"
      },
      "shippingAddress": {
        "region": "CN",
        "city": "XX",
        "address1": "XXX"
      },
      "shippingCarrier": "",
      "shippingPhoneNo": "7567***4534"
    }
  },
  "merchantInformation": {
    "referenceMerchantId": "M00000000000",
    "merchantMCC": "1405",
    "merchantName": "UGG",
    "merchantAddress": {
      "region": "JP",
      "city": "xxx"
    },
    "store": {
      "referenceStoreId": "S0000000000",
      "storeName": "UGG-2",
      "storeMCC": "1405"
    }
  },
  "endUserInformation": {
    "referenceBuyerId": "S0000000000",
    "buyerName": {
      "firstName": "Jay",
      "middleName": "Chou",
      "lastName": "Chou",
      "fullName": "Jay Chou"
    },
    "buyerPhoneNo": "XXX",
    "buyerEmail": "abc@example.com"
  }
}
```

## Response

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