In this section you can learn about:

When a customer opens up a dispute, Clearpay call the webhook with webhook_event_type = created.
Merchants can use the Get Dispute endpoint below to get the detailed information of the dispute.

Receiving disputes

Get Dispute - Endpoint

GET https://global-api.afterpay.com/v2/disputes/{dispute_id}

Connection Timeouts

Timeout	Time (seconds)
`OPEN`	10
`Read`	20

Request Headers

Header	Type	Default Value
`User-Agent`	String	Clearpay Online API Simulator
`Accept`	String	application/json

Request Parameters

Field name	Data type	Description
`dispute_id`	String	(Required) Dispute identifier

Response

Field name	Data type	Description
`dispute`	DisputeObject	The updated dispute object

Dispute Object

Field name	Data type	Description
`id`	String	Dispute identifier.
`order`	String	The token of the order that is disputed.
`amount`	String	The amount of the dispute. (Example: 40.13).
`currency`	String	Currency of the dispute. (ISO-4217 standard, example: GBP).
`reason`	String	Reason for the dispute. See the section on recommended Dispute Reasons below.
`status`	String	The current state of the dispute. Values depend on how the dispute state machine is modeled. See the section on recommended Dispute Status below.
`open`	Boolean	`True` if a final decision on the dispute hasn’t been made yet.
`responseDueBy`	Timestamp	Deadline by which the merchant must respond to this dispute. (Epoch timestamp in seconds, Timezone: UTC +0:00).
`createdAt`	Timestamp	A timestamp indicating when the dispute was created. (Epoch timestamp in seconds, Timezone: UTC +0:00).
`openingNote`	String	A text blob from the customer describing why the dispute was opened or the reason for their complaint. Dispute category codes are helpful to inform what evidence a merchant should present. However the codes do not provide the reasoning behind the customer’s complaint. In some cases, this text description can help you troubleshoot the dispute directly with your customer.
`openingNoteAttachments`	FileId	Attachments to supplement the `openingNote`. If the customer provided photos or screenshots then they are attached here.
`updatedAt`	Timestamp (optional)	Timestamp when the dispute was updated. (Epoch timestamp in seconds, Timezone: UTC +0:00)
`closingReason`	String	A reason that shows how the final decision on the dispute was reached. Recommended possible values are listed in Closing Reasons below.
`closingNote`	String (optional)	A text blob that describes in detail how the final decision on the dispute was reached. This supplements the `closingReason`.
`merchantOrderId`	String	The identifier for the transaction on the merchant side.
`transactionDate`	Timestamp	The timestamp of the order created by the customer. (Epoch timestamp in seconds, Timezone: UTC +0:00)
`settlementAmount`	String	The settlementAmount for audit purposes.
`meta`	MetaObject (Optional)	The extra information for merchants to match a payment.

Meta Object

Field name	Data type	Description
`transactionAmount`	String	The transaction amount for the order.
`network`	String (Optional)	The payment network used by the customer. Typically, Visa or MasterCard.
`networkReferenceId`	String(Optional)	The identifier for the payment. (For in-store payments, the field exists)
`orderType`	String	The type of the order, should be either `ONLINE` or `INSTORE`.

Dispute Object Example

Field name	Data type	Example
`id`	String	dp_N64jYg4RC4ZBUsXjLzE3W5
`order`	String	123456789
`amount`	String	48.46
`currency`	String	GBP
`reason`	String	fraudulent
`status`	String	won
`open`	Boolean	false
`responseDueBy`	Timestamp	1691884800
`createdAt`	Timestamp	1691884800
`openingNote`	String	Customer has no knowledge of the payment.
`openingNoteAttachments`	FileId	[“fi_48vmw3sXdVqvtJGXbgKbAZ”]
`updatedAt`	Timestamp (optional)	1691884800
`closingReason`	String	merchant_accepted
`closingNote`	String (optional)	Merchant accepted the dispute.
`merchantOrderId`	String	merchantorderid12345
`transactionDate`	Timestamp	1691884800
`settlementAmount`	String	48.46
`meta`	MetaObject (Optional)	`{ <br /> <space> "transactionAmount": "48.46",<br /> "orderType":"ONLINE" <br /> }`

Dispute Status

Clearpay supports the following dispute status:

Note

We currently don’t support the partially_won status.

Status	Description
`needs_response`	Clearpay has created the dispute and notified the merchant, but the merchant has not taken action.
`under_review`	Merchant has submitted evidence to Clearpay, and it is currently under review.
`partially_won`	If the final dispute settlement was less than the original dispute amount, then this indicates the merchant partially won the dispute. This is a terminal state. Note: Currently we do not support this `partially_won` status.
`won`	The evidence submitted is accepted by Clearpay and the dispute is won by the merchant. This is a terminal state.
`lost`	The evidence submitted is rejected by Clearpay and the dispute is lost by the merchant. This is a terminal state.

Dispute Windows

Clearpay updates the dispute status and triggers dispute notifications according to the dispute window time frames. The following is the time frame (in calendar days) to process and defend a dispute:

Summary	Description	Cut-off time
Dispute Open Window	The maximum window of time (from the transaction date) to open a dispute. Customers cannot open disputes beyond this time.	120 days
Merchant’s Evidence Submission Window	The time allowed between the merchant being notified of a dispute and the final time for evidence submission.	13 days
Clearpay’s Decision Window	The time allowed from the moment of evidence submission to Clearpay’s final decision.	Target of 30 days

Dispute Reasons

There is always a dispute reason when a dispute is triggered. The current dispute reasons available are:

Merchant-facing Dispute Reason	Description
`product_not_received`	The customer claims they did not receive the products or services purchased.
`goods_not_as_described`	The product or service was received, but was defective, damaged, or not as described.

Closing Reasons

A closing reason indicating how the final decision on the dispute was reached is displayed to the merchant. The following are the closing reasons and their descriptions:

Merchant-facing Closing Reason	Description
`merchant_accepted`	Merchant accepted the dispute.
`evidence_accepted`	Merchant submitted evidence which was accepted, the dispute was closed in the merchant’s favour.
`evidence_rejected`	Merchant submitted the evidence but it was rejected and the dispute was closed in the customer’s favour.
`deadline_expired`	Merchant failed to submit evidence for the dispute and the submission window timed out. Dispute was closed in the customer’s favour.
`customer_cancelled`	Customer withdrew the dispute and therefore it was closed in the merchant’s favour.

Retrieving disputes

List Disputes - Endpoint

List disputes within a date range based on certain criteria. This endpoint can be used for debugging or synchronising the disputes from Clearpay if/when you are unable to use the webhook method.

GET https://global-api.afterpay.com/v2/disputes

Connection Timeouts

Timeout	Time (seconds)
`OPEN`	10
`Read`	20

Request Headers

Header	Type	Default Value
`User-Agent`	String	Clearpay Online API Simulator
`Accept`	String	application/json

Request Parameters

Field name	Data type	Description
`order`	Integer	Payment or Order token using which you can filter the list.
`merchant`	String	Merchant token using which you can filter the list.
`status`	String	Dispute status using which you can filter the list.
`openedAfter`	Timestamp	Filter disputes that were created on or after this timestamp (inclusive).
`openedBefore`	Timestamp	Filter disputes that were created on or before this timestamp (inclusive).
`offset`	Integer	Offset for the search results. Example: Offset = 0, limit = 10 means that we will display the first ten disputes. Offset = 10, limit = 10 means that we will display the disputes numbered 10-20 in the search results.
`limit`	Integer	The maximum number of records that you want returned from this request.

Response

Field name	Data type	Description
`data`	Array (DisputeObject)	An array of dispute objects that match the filter criteria in the request.
`offset`	Integer	Offset for the search results. Example: Offset = 0, limit = 10 means that we will display the first ten disputes. Offset = 10, limit = 10 means that we will display the disputes numbered 10-20 in the search results.
`limit`	Integer	The maximum number of records that you want returned from this request.
`total`	Integer	Total dispute records in the search condition.

Response Example

Field name	Data type	Example
`data`	Array (DisputeObject)	See Data example code below.
`offset`	Integer	0
`limit`	Integer	1
`total`	Integer	1

Data example code

1 [
2   {
3     "id": "dp_N64jYg4RC4ZBUsXjLzE3W5",
4     "order": "12312312312",
5     "amount": "48.46",
6     "currency": "GBP",
7     "status": "won",
8     "reason": "product_not_received",
9     "open": false,
10     "responseDueBy": -1,
11     "openingNote": "Customer has no knowledge of delivery.",
12     "openingNoteAttachments": [],
13     "merchantOrderId": "12312312312",
14     "transactionDate": 1690836227,
15     "createdAt": 1691884800,
16     "updatedAt": 1692067909,
17     "meta": {
18               "transactionAmount": "48.46",
19               "orderType": "ONLINE"
20             }
21   }
22 ]