Integrate with the Disputes API

Merchants can integrate directly with the Disputes API to scale their disputes process and integrate with other order management and customer service tools. This is helpful for merchants who handle a high volume of transactions.

Dispute notifications

Afterpay notifies merchants using webhooks when a dispute is created and any time it is updated. Afterpay expects the ACK (acknowledgement) with a 200 response. If the acknowledgement fails, Afterpay will reattempt 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 get the details for the dispute.

Notification setup

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

The webhook endpoint should be maintained by merchants or partners, it should 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

Afterpay recommends that you use HMAC for the authentication of the webhook notification. Consider the following structure of the raw HTTP message.

1
POST ${notification_uri} HTTP/1.1
2
Host: ${notification_base_url}
3
X-Afterpay-Request-Date: 1664239810
4
X-Afterpay-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 will be two extra fields for authentication.

• X-Afterpay-Request-Date records the send time for the webhook request. We recommned aborting the stale notification after a fixed time (if you receive the webhook and current timestamp - ${X-Afterpay-Request-Date} is greater than 5 minutes).

• X-Afterpay-Request-Signature records the signature of the HMAC key. Typically we generate the signature using the following steps:

  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)

When a merchant or merchant agency receives a webhook notification, we recommend generating verification signatures in following steps.

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

Series of events