# responseRetrieval The **responseRetrieval** API is used by Alipay+ to send the information that is required in a retrieval request to the Mobile Payment Provider (MPP), as a reply to the MPP's **initiateRetrieval** request. Alipay+ must send the response by using the **responseRetrieval** API within 20 days after the MPP's 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 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". > > - 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 the MPP to identify a retrieval request. More information: - This field is an API idempotency field.For requests that are initiated with the same disputeRequestId, the MPP needs to return the same result. - Maximum length: 64 characters #### responseCode (String, REQUIRED) The code that reflects whether the Acquiring Partner (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. This parameter is specified by Alipay+ if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified as `TRANSACTION_RECEIPT`. However, 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 ##### orderAmount (Amount, REQUIRED) The original order amount that is displayed by the merchant to the customer on the consumption records or payment result page. The value of _transactionReceipt.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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited ##### goods (Array, 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. ###### 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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1. More information: - Value range: 1 - unlimited ###### goodsQuantity (Integer) The quantity of the goods. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. 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. This parameter is specified by Alipay+ if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by the MPP as `PROOF_OF_DELIVERY`. However, 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) The name of the shipping recipient. ###### firstName (String) The first name of the user.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### middleName (String) The middle name of the user. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### lastName (String) The last name of the user. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### shippingCarrier (String) The name of the shipping carrier, such as FedEx, UPS, or USPS.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 128 characters ###### shippingPhoneNo (String) The contact number of the shipping recipient. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 16 characters #### merchantInformation (Merchant) The merchant information.  This parameter is specified by Alipay+ if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by the MPP as `MERCHANT_INFORMATION`. However, If the value of _otherDocumentation_ contains `MERCHANT_INFORMATION`, this parameter can be empty. ##### referenceMerchantId (String, REQUIRED) The unique ID that is assigned by Alipay+ 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, REQUIRED) The legal name of the merchant. More information: - Maximum length: 256 characters ##### merchantAddress (Address, REQUIRED) In the Cashier Payment and Auto Debit scenarios, the address indicates the region where the merchant is registered. In the User-presented Mode and Merchant-presented Mode Payment scenarios, the address indicates 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. code More information: - Maximum length: 32 characters ##### merchantDisplayName (String) The display name of the merchant. The default value of this parameter is the value of the _merchantName_ parameter. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ##### merchantRegisterDate (Datetime) The time when the merchant registered its business at the local regulatory agency. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### storeTerminalId (String) The unique ID that is assigned by the merchant to identify a store terminal. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. ###### 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### city (String) The city, district, suburb, town, or village where the address is located. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ###### address1 (String) The address line 1, which contains the street name, PO box, or company name.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### address2 (String) The address line 2, which contains the apartment, suite, unit, or building name. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 256 characters ###### zipCode (String) The zip or postal code. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters #### endUserInformation (Buyer) The information of the end-user, also called the buyer. This parameter is specified by Alipay+ if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by the MPP as `END_USER_INFORMATION`. However, 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 to identify a buyer. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters ##### buyerName (UserName) The name of the buyer. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. ###### firstName (String) The first name of the user.  This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### middleName (String) The middle name of the user. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 32 characters ###### lastName (String) The last name of the user. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. 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. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 24 characters ##### buyerEmail (Email) The email address of the buyer. This parameter is specified by Alipay+ if the relevant information is passed in by the merchant. More information: - Maximum length: 64 characters #### otherDocumentation (Array) The list of any other documents that are required. This parameter is specified by Alipay+ if _responseCode_ is `0001` and _requestInformationType_ in the **initiateRetrieval** API is specified by the MPP 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. This parameter is specified by Alipay+ 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.  This parameter is specified by Alipay+ 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`. This parameter is specified by Alipay+ if _content_ is specified. More information: - Maximum length: 8 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. It is recommended that you specify this parameter to provide details about the result. 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 | | --- | --- | --- | | SUCCESS | S | Success | | ACCESS_DENIED | F | Access is denied. | | EXCEEDS_RETRIEVAL_RESPONSE_TIME_LIMIT | F | The request exceeds retrieval response time limits. | | 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 does not exist. | | PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | | PROCESS_FAIL | F | A general business failure occurred. Do not retry. | | 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", "responseCode": "0001", "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" } } ```