# responseEscalation `POST /aps/api/v1/disputes/responseEscalation` The **responseEscalation** API is used by the Acquiring Service Provider (ACQP) to send the information that is related to an escalation to Alipay+, as a reply to Alipay+'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:** 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_, Alipay+ returns `REPEAT_REQ_INCONSISTENT` for the second request. More information: - This field is an API idempotency field. - Maximum length: 64 characters #### refundType (String, REQUIRED) The refund result that reflects whether the ACQP agrees to 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:** - Required 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 Alipay+ 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. - The value of _refundAmount.currency_ needs to be the same as the value of _paymentAmount.currency_ in the **pay** 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.  Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`. More information: - Value range: 1 - unlimited #### plannedRefundTime (Datetime) The date and time when the ACQP plans to process the refund. **Note:** It is recommended to specify this parameter if _refundType_ is `ACCEPT_REFUND` or `ACCEPT_PARTIAL_REFUND`. 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) Transaction receipt of the payment. **Note:** For when to specify this parameter, see _How to specify request parameters_. ##### 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 ##### orderStatus (String, REQUIRED) The order status on the merchant side. Valid values are: - `SUCCESS`: The order succeeds. - `FAILED`: The order failed. - `CANCELLED`: The order is canceled. - `REFUND`: The order is refunded. - `PARTIAL_REFUND`: The order is partially refunded. - `CHARGEBACK`: The order is charged back. - `UNKNOWN`: The order status is unknown. ##### 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.  Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`. More information: - Value range: 1 - unlimited ##### goods (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: 64 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. Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`. 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) 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:** For when to specify this parameter, see _How to specify request parameters_. ##### deliveryTrackingNo (String, REQUIRED) The tracking number of the delivery. More information: - Maximum length: 128 characters ##### shipping (Shipping, REQUIRED) 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:** For when to specify this parameter, see _How to specify request parameters_. ##### referenceMerchantId (String, REQUIRED) The unique ID that is assigned by the ACQP to identify a merchant. More information: - Maximum length: 32 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, REQUIRED) 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: 32 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:** For when to specify this parameter, see _How to specify request parameters_. ##### 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 (String) 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) The list of any other documents. **Note:** For when to specify this parameter, see _How to specify request parameters_. ##### 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:** It is recommended to specify this parameter if the ACQP wants to pass any information to the Mobile Payment Provider. 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 ## How to specify request parameters _transactionReceipt_&_proofDelivery_&_merchantInformation_&_endUserInformation_&_otherDocumentation_: If the value of _refundType_ is `ACCEPT_PARTIAL_REFUND` or `REFUSE_REFUND`, at least one of these 5 parameters needs to be specified. ## Result/Error codes | Code | Value | Message | Further action | | --- | --- | --- | --- | | SUCCESS | S | Success | N/A | | ACCESS_DENIED | F | Access is denied. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Ensure that the value of refundAmount.currency is the same as the value of paymentAmount.currency in the pay API. | | EXCEEDS_ESCALATION_RESPONSE_TIME_LIMIT | F | The time limit of the escalation response for the transaction is exceeded. | Ensure that the escalation is responded to within 20 days after being received. | | INVALID_CLIENT | F | The client is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | INVALID_SIGNATURE | F | The signature is invalid. | Check whether the public key, signed message, and signature algorithm are as expected. | | KEY_NOT_FOUND | F | The server does not implement the media type that is acceptable to the client. | Use a media type that is accepted by Alipay+. | | METHOD_NOT_SUPPORTED | F | API is not defined. | Check whether the request URL is correct. Ensure that the endpoint of the called API is correct. | | ORDER_NOT_EXIST | F | The order doesn't exist. | Ensure that the value of disputeRequestId is correct. | | PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of each API, see the Structure section of the specific API reference topic. | | PROCESS_FAIL | F | A general business failure occurred. Do not retry. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | REFUND_AMOUNT_EXCEED_LIMIT | F | The refund amount exceeds the escalation amount. | Ensure that the value of refundAmount.value is lower than the value of escalationAmount.value in the initiateEscalation API. | | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Reduce the frequency of API calls. | | UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. | Try to recall the API. | ## Request ```json { "disputeRequestId": "201811291907410200070000000000", "refundType": "ACCEPT_PARTIAL_REFUND", "refundAmount": { "currency": "JPY", "value": "50" }, "plannedRefundTime": "2020-10-10T12:01:01+08:30", "transactionReceipt": { "referenceOrderId": "orderID_0101010000", "orderAmount": { "value": "200", "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": "75670004534" } }, "merchantInformation": { "referenceMerchantId": "M00000000000", "merchantMCC": "1405", "merchantName": "UGG", "merchantAddress": { "region": "JP", "city": "xxx" }, "store": { "referenceStoreId": "S0000000000", "storeName": "UGG-2", "storeMCC": "1405" } }, "endUserInformation": { "userName": { "firstName": "Jay", "middleName": "Chou", "lastName": "Chou", "fullName": "Jay Chou" }, "nationality": "nationality", "userAddress": { "region": "CN", "city": "XX", "address1": "XXX" }, "userEmail": "abc@example.com" } } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "success", "resultStatus": "S" } } ```