initiateRetrievalAlipay+ → ACQP
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:
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 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 object
The result of the business processing, including the result status, result code, and the result message.
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
Request
Response
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. |