Dispute Status

Primer notifies you with a DISPUTE.STATUS webhook that will provide information on retrievals, disputes (also known as chargebacks), and preabritration filings.

This notification is supported for Adyen, Airwallex, Braintree, Checkout.com, PayPal & Stripe.

The DISPUTE.STATUS event can be used to proactively communicate with customers, issue refunds, send disputes to risk tools, or to proactively defend disputes.

The DISPUTE.STATUS event is currently in an open beta stage, as we continue to add more processors.

Learn more about managing disputes at Primer.

Webhook

Version - 2.4

Example of dispute event

{
  "eventType": "DISPUTE.STATUS",
  "version": "2.4",
  "type": "DISPUTE",
  "status": "CHALLENGED",
  "primerAccountId": "acct_123456789",
  "transactionId": "txn_987654321",
  "orderId": "order_12345",
  "paymentId": "pay_67890",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "network": "VISA",
      "last4": "1234",
      "expiry": "12/25"
    }
  },
  "processor": "ADYEN",
  "processorDisputeId": "dispute_123456789",
  "receivedAt": "2025-09-23T13:00:00Z",
  "challengeRequiredBy": "2025-10-07T13:00:00Z",
  "reason": "Fraudulent transaction",
  "reasonCode": "4800",
  "processorReason": "Chargeback reason code 4800",
  "amount": 1000,
  "currency": "GBP",
  "merchantId": "merchant_12345"
}

Webhook

Version - 2.4

Example of dispute event

{
  "eventType": "DISPUTE.STATUS",
  "version": "2.4",
  "type": "DISPUTE",
  "status": "CHALLENGED",
  "primerAccountId": "acct_123456789",
  "transactionId": "txn_987654321",
  "orderId": "order_12345",
  "paymentId": "pay_67890",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "network": "VISA",
      "last4": "1234",
      "expiry": "12/25"
    }
  },
  "processor": "ADYEN",
  "processorDisputeId": "dispute_123456789",
  "receivedAt": "2025-09-23T13:00:00Z",
  "challengeRequiredBy": "2025-10-07T13:00:00Z",
  "reason": "Fraudulent transaction",
  "reasonCode": "4800",
  "processorReason": "Chargeback reason code 4800",
  "amount": 1000,
  "currency": "GBP",
  "merchantId": "merchant_12345"
}

Headers

X-Signature-Primary · string · required

An HMAC signature generated using the webhook payload and a shared signing secret. This is then converted to a base64 encoded string.

X-Signature-Secondary · string · required

A secondary signature that is added when you have rotated your secret within the past 24 hours.

Body

application/json

eventType · string · required

The type of event that triggered the webhook. This will have the value DISPUTE.STATUS. This indicates that a dispute notification was issued through a configured connection.

Use these notifications to proactively communicate with your customer, issue refunds, or submit evidence to challenge disputes.

type · enum<string> · required

The type of dispute event. More information on what the type field represents can be found in Manage disputes

Available options: RETRIEVAL, DISPUTE, PREARBITRATION

status · enum<string> · required

To see which statuses are applicable for a dispute type, and how we map status, please see Manage disputes.

Available options: OPEN, ACCEPTED, CHALLENGED, EXPIRED, CANCELLED, WON, LOST

primerAccountId · string · required

A unique identifier for your Primer merchant account.

orderId · string · required

Your reference for the sale transaction that the dispute relates to.

paymentId · string · required

A unique identifier for the Primer payment corresponding to this dispute.

paymentMethod · Payment Method Information · object · required

The payment method information for the payment that is now disputed.

Show child attributes

processor · enum<string> · required

The payment processor that you submitted a payment to, and received a dispute notification from.

Available options: ADYEN, AIRWALLEX, BRAINTREE, CHECKOUT, PAYPAL, STRIPE

processorDisputeId · string · required

An identifier for this dispute provided by the processor. This is shared across multiple dispute type and status relating to the same payment.

e.g. as an open dispute that is later challenged will share a proccessorDisputeId.

receivedAt · string<date-time> · required

Date and time at which Primer received the processor's dispute event. Provided as an ISO timestamp in UTC.

challengeRequiredBy · string<date-time> · required

Time by which the merchant must challenge a dispute. This is provided by the processor, where available.

reasonCode · string · required

The dispute reason code for a dispute. This will be the same code provided by the card schemes.

amount · integer<int64> · required

The disputed amount. Note: this is not always the same as the payment amount.

This will be displayed in minor units.

e.g. for $7, use 700. Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use 100.

currency · string · required

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

version · string

The payload version

Example:

"2.4"

transactionId · string

A unique identifier for the Primer transaction corresponding to this dispute.

reason · string

Primer's unified reason that explains why the dispute was raised. This should not vary across processors for the same dispute reasonCode, unlike the processorReason.

processorReason · string

The dispute reason provided by the processor. This can vary across processors for the same dispute reasonCode, which is why we provide a unified field - reason.

merchantId · string

The merchant ID registered at the payment processor used for this dispute.

Response

200

Return a 200 status to indicate that the data was received successfully