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:
1. 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".
2. 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 Alipay+ to identify a retrieval request.
Important: 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.For requests that are initiated with the same disputeRequestId, the ACQP must regard the requests as repeated and process the requests only once. The ACQP is recommended to check the consistency of the paymentRequestId parameter. If its value is different from that in the previous request, the ACQP needs to return the REPEAT_REQ_INCONSISTENT result code.
- 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.
This parameter is 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.
disputeId String
The unique ID that is assigned by the ACQP to identify a retrieval request.
Specify this parameter if result.resultStatus is S
.
More information:
- Maximum length: 64 characters
Request
Response
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 toSUCCESS
. - 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_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. |