Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

notifyDispute

This API is used by APO to send the dispute information to the merchant. 

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

acquirerInfo AcquirerInfo  

The information of the acquirer that processes the payment.

Show child parameters

paymentRequestId String  REQUIRED

The unique ID that is assigned by a merchant to identify a payment request. 

More information:

  • Maximum length: 64 characters

disputeId String  REQUIRED

The unique ID that is assigned by APO to identify a dispute.  

More information:

  • Maximum length: 64 characters

paymentId String  REQUIRED

The unique ID that is assigned by APO to identify a payment.  

More information:

  • Maximum length: 64 characters

disputeTime Datetime  

The date and time when the dispute is created.  

More information:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

disputeAmount Amount  

The amount of the transaction which has a dispute. 

Note: This parameter is returned when a dispute occurs.  

Show child parameters

disputeNotificationType String  REQUIRED

The type of dispute notification. Valid values are:

  • DISPUTE_CREATED: indicates that a dispute occurs.
  • DISPUTE_JUDGED: indicates that the dispute is judged.  

More information:

  • Maximum length: 30 characters

disputeReasonMsg String  

The dispute reason.   

More information:

  • Maximum length: 256 characters

disputeJudgedTime Datetime  

The date and time when the dispute is judged.  

More information:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

disputeJudgedAmount Amount  

The deduction amount of the dispute. 

Note: This parameter is returned when a dispute is judged.

Show child parameters

disputeJudgedResult String  

The result of the dispute judgement. Valid values are: 

  • ACCEPT_BY_CUSTOMER: indicates that the dispute is judged to be the buyer's responsibility. The acquirer unfreezes the captured funds and you can handle the funds freely.
  • ACCEPT_BY_MERCHANT: indicates that the dispute is judged to be the merchant's responsibility. The acquirer unfreezes the captured funds but deduct from your settlement account to refund the buyer. 

More information:

  • Maximum length: 30 characters

defenseDueTime Datetime  

The due time after which you cannot defend the dispute. 

Note: This parameter is returned when the value of disputeNotificationType is DISPUTE_CREATED or DEFENSE_DUE_ALERT.

disputeReasonCode String  

The reason code indicating why a payment is disputed. For details about the reason codes, see Chargeback reason codes.

Note: This parameter is returned when the value of disputeNotificationType is DISPUTE_CREATED or DISPUTE_JUDGED.

More information:

  • Maximum length: 64 characters

disputeSource String  

The card scheme that is responsible for processing the dispute.

Note: This parameter is returned when the value of disputeNotificationType is DISPUTE_CREATED or DISPUTE_JUDGED.

More information:

  • Maximum length: 64 characters

arn String  

Acquirer reference number (ARN) of the dispute.

Note: This parameter is returned when the value of disputeNotificationType is DISPUTE_CREATED.

More information:

  • Maximum length: 64 characters

disputeAcceptReason String  

Reasons for accepting disputes. Specify this parameter when the value of disputeNotificationType is DISPUTE_ACCEPTED. Valid values are:

  • MERCHANT_ACCEPTED: indicates acceptance of the dispute initiated by the merchant.
  • TIMEOUT: indicates acceptance of the dispute due to a timeout scenario, wherein if the merchant fails to defend the dispute within the designated timeframe, the dispute will be automatically accepted.
  • MANUAL_PROCESSING_ACCEPTED: indicates acceptance of the dispute due to the manual processing.

disputeAcceptTime Datetime  

The time when the dispute is accepted.

Note: Specify this parameter when the value of disputeNotificationType is DISPUTE_ACCEPTED.

disputeType String  REQUIRED

The dispute type. The valid values includes:

  • CHARGEBACK: indicates that the dispute type is chargeback.
  • ​RETRIEVAL_REQUEST​：indicates that the dispute type is retrieval request.
  • ​COMPLIANCE_REQUEST：indicates that the dispute type is compliance request.

More information:

  • Maximum length: 64 characters

defendable Boolean  

Indicates whether the dispute is defendable. Valid values are:

  • true: Indicates the dispute is defendable and this chargeback will need you to handle it.
  • false: Indicates the dispute is not defendable and this chargeback will be handled by the acquirer subsequently.

captureId String  

The unique ID that is assigned by APO to identify a capture.

Note: Specify this field to associate with the corresponding chargeback notice request if there are mutiple capture request.

More information:

  • Maximum length: 64 characters

autoDefendReason String  

The automatic defense reason.

Note: This parameter is only applicable when the value of defendable is false and a chargeback occurs.

More information:

  • Maximum length: 256 characters

Response parameters

result Result  REQUIRED

A fixed value, which is sent to APO to acknowledge that the notification is received.  

Show child parameters
API Explorer

Request

Case
Notification about an occurred dispute
Request Body

Response

Response Body

Result process logic

Send the following message with fixed values to APO after receiving the notification, to acknowledge that the notification from APO is received:

Sample Code

If no such message is returned to APO due to operation issues or network issues, APO will intermittently send the notification until the required message is returned by the merchant. Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to eight times, with an interval of 0s, 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

Note: In the sandbox environment, if you do not return information in the specified format, APO will not resend asynchronous notifications to you.

Result/Error codes

CodeValueMessage
SUCCESSSSuccess