Alipay+ DocsAlipay+ Docs
APIs & SDKs

initiateRetrievalAlipay+ ACQP

POST /aps/api/v1/disputes/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: 

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. 

Show child parameters

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

Request

Request Body

Response

Response Body

Result/Error codes

CodeValueMessage
SUCCESSSSuccess
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.