Alipay+ DocsAlipay+ Docs

initiateEscalationAlipay+ ACQP

The initiateEscalation API is used by Alipay+ to send an escalation initiation request to the Acquiring Partner (ACQP ). When using this API, the ACQP needs to take the following things into consideration:

  • Only Mobile Payment Partners (MPPs) can initiate an escalation.
  • For each transaction, a maximum of 2 escalations can be requested (excluding those that are canceled), while a transaction can have only 1 ongoing escalation.
  • Escalation request time limits:
    • Within 360 days after the original transaction, the MPP can initiate the first escalation;
    • Within 25 days after the first escalation is replied to or closed, the MPP can initiate the second escalation.
  • Escalation amount: The escalation amount cannot exceed the maximum available dispute amount.
  • Special Merchant: Currently this includes Apple and Google. They require additional information for escalation initiation. 

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

For optional parameters that are not required in your case, you can:

  • exclude it from the request body. 
  • set its value as null (without the double quotation marks).

Do NOT leave it empty by setting its value as ""; otherwise, an error might occur. 

Request parameters

disputeRequestId String  REQUIRED

The unique ID that is assigned by Alipay+ to identify an escalation.

Important: If two requests specify the same value for disputeRequestId but different values for paymentRequestId, the ACQP needs to return 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 escalation occurs.

More information:

  • Maximum length: 64 characters

disputeOccurTime Datetime  REQUIRED

The date and time when the escalation occurs. For the ACQP, this parameter refers to the date and time when Alipay+ starts handling the escalation.

disputeReasonCode String  REQUIRED

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

  • 7801: The code for merchandise-related reasons, which is used for an escalation.
  • 7802: The code for transaction-processing-related reasons, which is used for an escalation.
  • 7803: The code for fraud-related reasons, which is used for an escalation. 

disputeReasonCodeDescription String  REQUIRED

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

  • MERCHANDIZE_OR_SERVICE_NOT_RECEIVED: specified if reasonCode is 7801, indicating that the merchandise/service is not received.
  • NOT_AS_DESCRIBED: specified if reasonCode is 7801, indicating that the merchandise/service is not as described.
  • REFUND_NOT_PROCESSED: specified if reasonCode is 7801, indicating that the refund is not processed.
  • AMOUNT_DIFFER: specified if reasonCode is 7802, indicating that there exists a difference between amounts.
  • DUPLICATE_PROCESSED: specified if reasonCode is 7802, indicating that the transaction is processed duplicately.
  • PAIDED_BY_OTHER_MEANS: specified if reasonCode is 7802, indicating that the transaction is paid by other means.
  • USER_DENIED_PARTICIPANTING_IN_A_TRANSACTION: specified if reasonCode is 7803, indicating that the user denied participating in the transaction. 

escalationAmount Amount  REQUIRED

The escalation amount.

The value of escalationAmount.value cannot exceed the maximum available dispute amount. 

Show child parameters

merchantDisputeId String  

The unique ID that is assigned by the merchant to identify an escalation.

This parameter is specified by Alipay+ for transactions of Special Merchants. 

More information:

  • Maximum length: 32 characters

customerIdAssignedByMerchant String  

The unique ID that is assigned by the merchant to identify an escalation.

This parameter is specified by Alipay+ for transactions of Special Merchants. 

More information:

  • Maximum length: 32 characters

customerIdAssignedByMerchant String  

The unique ID that is assigned by the merchant to identify a customer. 

This parameter is specified by Alipay+ for the transactions of Special Merchants, with the exception of Apple and Google, where the value of this parameter is provided by the user.   

More information:

  • Maximum length: 32 characters

merchantNotRefundRecord Array<Attachment>  

The list of supporting documents that are used to prove that the merchant does not refund.

This parameter is specified by Alipay+ for the transactions of Special Merchants, with the exception of Apple and Google, where the documents are provided by the user. 

Show child parameters

supportingDocumentation Array<Attachment>  

The list of documents that are used to support the escalation. 

Show child parameters

remarks String  

Supplementary information.

This parameter is specified by Alipay+ if there's any additional information that needs to be remarked. 

More information:

  • Maximum length: 1024 characters

Response parameters

result Result  REQUIRED

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 an escalation.

Return this parameter if result.resultStatus is S

More information:

  • Maximum length: 64 characters
API Explorer

Request

Request Body

Response

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

CodeValueMessage
SUCCESSSSuccess
ACCESS_DENIEDFThe escalation amount exceeds the transaction amount with no discount.
EXCEEDS_ESCALATION_REQUEST_LIMITFThe number limit of the escalation request for the transaction is exceeded.
EXCEEDS_ESCALATION_REQUEST_TIME_LIMITFThe time limit of the escalation 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 doesn't exist.
PARAM_ILLEGALFIllegal parameters. For example, non-numeric input, invalid date.
PROCESS_FAILFA general business failure occurred. Do not retry.
SPECIAL_MERCHANT_REQUIRES_MERCHANT_CUSTOMER_IDFcustomerIdAssignedByMerchant is required of Special Merchants.
SPECIAL_MERCHANT_REQUIRES_MERCHANT_DISPUTE_IDFmerchantDisputeId is required of Special Merchants.
SPECIAL_MERCHANT_REQUIRES_MERCHANT_NOT_REFUND_RECORDFmerchantNotRefundRecord is required of Special Merchants.
REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
UNKNOWN_EXCEPTIONUAn API call failed, which is caused by unknown reasons.