End-to-end Dispute Flow

An overview of the end-to-end dispute flow is:

1. Clearpay receives a dispute from the customer.
2. Clearpay notifies the merchant with a dispute reason code for the dispute.
3. The merchant is notified that a dispute is opened.
4. The merchant accepts the reason for the dispute and the dispute is over. Or the merchant challenges the reason for the dispute and submits evidence through the API or the UK Business Hub. This response and evidence is sent to the customer for review.
5. The customer accepts the merchant is correct and the dispute is over. Or the customer rejects the merchant’s assertion and evidence. The dispute now goes to Clearpay for adjudication.
6. Clearpay assesses the evidence and notifies the merchant if the dispute is won or lost.
7. Clearpay notifies the customer that the dispute is won or lost.

Merchant Side Dispute Lifecycle Diagram

Merchant Side Dispute API Integration Diagram

API Endpoints Overview

This table lists the APIs provided to merchants:

Dispute Notifications

Clearpay notifies merchants using webhooks when a dispute is created and any time it is updated. Clearpay expects the ACK (acknowledgement) with a 200 response. If the acknowledgement fails, Clearpay reattempts sending the webhook a few times with exponential backoff.

The following table outlines the content for the webhook call:

A dispute_id is passed in the webhook call. Merchants can use the Get Dispute endpoint to obtain details of the dispute.

Notification Setup

You, the merchant, must provide a webhook URL and merchant IDs to the Clearpay merchant service/dispute team to get the HMAC key and enable the notification.

Merchants/partners should maintain the webhook endpoint. The endpoint must allow POST requests with content-type = application/json.

Notification Authentication

• (option 1) Key Exchange Wiki: Diffie-Hellman Key Exchange via Openssl: Quick Guide
• (option 2) Securely get HMAC key from https://squareup.sendsafely.com/

HMAC Signature

Clearpay recommends that you use HMAC for the authentication of the webhook notification.
Below is the structure of the raw HTTP message:

1
POST ${notification_uri} HTTP/1.1
2
Host: ${notification_base_url}
3
X-Clearpay-Request-Date: 1664239810
4
X-Clearpay-Request-Signature: ${signature}
5
Content-Type: application/json
6
{
7
    "webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe",
8
    "webhook_event_type": "created",
9
    "dispute_id": "dp_KvGaECApCMdsH8earUSa2V",
10
    "merchant_reference": "08CF65ZSFNHVM"
11
}

There are two extra fields for authentication.

• X-Afterpay-Request-Date records the send time for the webhook request. We recommend aborting the stale notification after a fixed time. For example, if you receive the webhook and current timestamp - ${X-Afterpay-Request-Date} after more than 5 minutes
• X-Afterpay-Request-Signature records the signature of the HMAC key. Typically we use the following steps to generate the signature:

1
PAYLOAD={"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type":       "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}
2
URL= "${partner_notification_uri}"
3
SECRET=<hmac secret key here>
4
TIME=1664239810
5
MESSAGE="$URL\n$TIME\n$PAYLOAD"
6
X-Afterpay-Request-Signature=$(printf "${MESSAGE}" | openssl dgst -hmac ${SECRET} -sha256   -binary | base64)

Dispute Decisions and Closures

Dispute Cancellation

You can close canceled disputes (for example, disputes that may have been opened in error and must be retracted) with customer_cancelled as the closing_reason.

Settlement and Reporting

In financial reporting, there is a separate record for a dispute. Order ID, Dispute ID, financial changes (+/-) are included in this record.