Alipay+ DocsAlipay+ Docs

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+


A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: 


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 object 

The result of the business processing, including the result status, result code, and the result message. 

Show child parameters

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
API Explorer


Request Body


Response Body

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

ACCESS_DENIEDFAccess is denied.
EXCEEDS_RETRIEVAL_REQUEST_TIME_LIMITFThe time limit of the dispute retrieval request for the transaction is exceeded.
INVALID_CLIENTFThe client is invalid.
INVALID_SIGNATUREFThe signature is invalid.
KEY_NOT_FOUNDFThe key is not found.
MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTPS method.
NO_INTERFACE_DEFFAPI is not defined.
ORDER_NOT_EXISTFThe order does not exist.
PARAM_ILLEGALFIllegal parameters. For example, non-numeric input, invalid date.
TRANSACTION_HAS_ONGOING_RETRIEVAL_REQUESTFOngoing dispute retrieval request exists for the transaction.
REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
UNKNOWN_EXCEPTIONUAn API call failed, which is caused by unknown reasons.