# initiateRetrieval

The **initiateRetrieval** API is used by Alipay+ to send a retrieval request to the Acquiring Service Provider (ACQP). When using this API, the ACQP needs to take the following things into consideration:

-   Only Mobile Payment Providers (MPPs) can initiate a retrieval request.
-   For each transaction, a maximum of **5** retrieval requests can be initiated (excluding those that are canceled), while a transaction can have only **1** ongoing retrieval request.
-   The MPP can only initiate retrieval requests within **360** days from the day when the transaction occurs.

When receiving the **initiateRetrieval** request, the ACQP sends a synchronous response to indicate the request acceptance result, and then uses the **responseRetrieval** API to send the required information to Alipay+. 

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

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

More information:

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

#### paymentRequestId (String, REQUIRED)

The unique ID that is assigned by the ACQP to identify a payment where the retrieval request occurs.

More information:

- Maximum length: 64 characters

#### disputeOccurTime (Datetime, REQUIRED)

The date and time when the retrieval request occurs. For ACQPs, this parameter refers to the date and time when Alipay+ starts handling the retrieval request.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

#### disputeReasonCode (String, REQUIRED)

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

-   `6801`: The code for risk-related reasons, which is used for a retrieval request.
-   `6802`: The code for non-risk-related reasons, which is used for a retrieval request.

#### requestInformationTypes (Array<String>, REQUIRED)

The type of information that is required by the MPP in the retrieval request. Valid values are:

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

#### remarks (String)

Supplementary information.

**Note:** Specified by Alipay+ if the MPP wants to pass any information to the ACQP and specifies the parameter when initiating a retrieval request.

More information:

- Maximum length: 1024 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

#### disputeId (String)

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

**Note:** Required if _result.resultStatus_ is `S`.

More information:

- Maximum length: 64 characters

## Result/Error codes

| Code | Value | Message |
| --- | --- | --- |
| SUCCESS | S | Success |
| ACCESS_DENIED | F | Access is denied. |
| EXCEEDS_RETRIEVAL_REQUEST_TIME_LIMIT | F | The time limit of the dispute retrieval request for the transaction is exceeded. |
| INVALID_CLIENT | F | The client is invalid. |
| INVALID_SIGNATURE | F | The signature is invalid. |
| KEY_NOT_FOUND | F | The key is not found. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. |
| NO_INTERFACE_DEF | F | API is not defined. |
| ORDER_NOT_EXIST | F | The order does not exist. |
| PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. |
| TRANSACTION_HAS_ONGOING_RETRIEVAL_REQUEST | F | Ongoing dispute retrieval request exists for the transaction. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
| UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. |

## Request

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

```json
{
  "disputeRequestId": "201811291907410200070000000000",
  "paymentRequestId": "202111291907410200070000000000",
  "disputeOccurTime": "2020-10-10T12:01:01+08:30",
  "disputeReasonCode": "6801",
  "requestInformationTypes": [
    "TRANSACTION_RECEIPT",
    "PROOF_OF_DELIVERY"
  ],
  "remarks": "remark"
}
```

## Response

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