# responseRetrieval `POST /aps/api/v1/disputes/responseRetrieval` The **responseRetrieval** API is used by the Acquiring Service Provider (ACQP) to send the information that is required in a retrieval request to Alipay+, as a reply to the Alipay+'s **initiateRetrieval** request. The ACQP must send the response by using the **responseRetrieval** API within 20 days after Alipay+ sends the retrieval 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 a retrieval request. More information: - This field is an API idempotency field. - Maximum length: 64 characters #### responseCode (String, REQUIRED) The code that reflects whether the Acquiring Service Provider (ACQP) has enough information and/or documents required by the MPP in the retrieval request. Valid values are: - `0001`: The ACQP has all the information and/or documents required by the MPP in the retrieval request. - `0002`: The ACQP has part of the information and/or documents required by the MPP in the retrieval request. - `0003`: The ACQP has none of the information and/or documents required by the MPP in the retrieval request. #### transactionReceipt (TransactionReceipt) All transaction receipts of the payment. **Notes:** - Required if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by Alipay+ as `TRANSACTION_RECEIPT`. - If the value of _otherDocumentation_ contains `TRANSACTION_RECEIPT`, this parameter can be empty. ##### 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. **Notes:** - Required if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by Alipay+ as `PROOF_OF_DELIVERY`. - If the value of _otherDocumentation_ contains `PROOF_OF_DELIVERY`, this parameter can be empty. ##### 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. **Notes:** - Required if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by Alipay+ as `MERCHANT_INFORMATION`. - If the value of _otherDocumentation_ contains `MERCHANT_INFORMATION`, this parameter can be empty. ##### 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, REQUIRED) 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. **Notes:** - Required if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by Alipay+ as `END_USER_INFORMATION`. - If the value of _otherDocumentation_ contains `END_USER_INFORMATION`, this parameter can be empty. ##### 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) The list of any other documents that are required. **Note:** Required if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by Alipay+ as `OTHER_INFORMATION`. ##### 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 ## Response parameters #### result (Result) 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 ## 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. | | EXCEEDS_RETRIEVAL_RESPONSE_TIME_LIMIT | F | The request exceeds retrieval response time limits. | Ensure that the retrieval request 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 key is not found. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. | | MEDIA_TYPE_NOT_ACCEPTABLE | 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 | The server does not implement the requested HTTPS method. | Ensure the HTTP method is POST. | | NO_INTERFACE_DEF | F | The order does not exist. | Ensure the value of disputeRequestId is correct. | | ORDER_NOT_EXIST | F | The order does not exist. | Ensure 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. | | 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 ### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT ```json { "disputeRequestId": "201811291907410200070000000000", "responseCode": "0001", "transactionReceipt": { "referenceOrderId": "orderID_01010100000", "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" } } ```