Dispute lifecycle

Full dispute lifecycle updates are currently available for Adyen, Airwallex, Braintree, Checkout.com and PayPal. For other supported processors - currently Worldline Connect, Worldline Direct, MPGS, Payplug, Reach, Stripe, and Worldpay - you will only receive a Webhook with a status of OPEN where the type is DISPUTE.

Disputes are created in Primer when they are generated by your payment processor.

All Primer disputes conform to a single dispute lifecycle, which makes them work the same way regardless of the payment services you use.

A dispute always has a dispute type (Retrieval, Dispute, and Pre-arbitration), and status that depends on the type.

Every time the status or type is updated, a new DISPUTE.STATUS webhook will be sent.

Dispute lifecycle

Visa and Mastercard do not investigate payments before raising a dispute. As a result, these payment methods skip RETRIEVAL and go straight to the DISPUTE event type.

Dispute Types

As in the diagram above, Primer’s disputes framework separates disputes into three different types: RETRIEVAL, DISPUTE and PREARBITRATION

RETRIEVAL

A RETRIEVAL signifies an investigation into a payment has been launched. For cards, this is launched by a card issuer. Depending on the results of this investigation, a DISPUTE may be raised, and the payment can be reversed. This dispute type is not used by all payment methods or card schemes - Visa and Mastercard do not support it.

status	Description
OPEN	Occurs when an investigation is launched into a payment. The merchant has not been debited for this yet.
EXPIRED	Occurs when a retrieval is opened and the merchant has taken too long to provide evidence in a challenge.
CHALLENGED	Occurs when a retrieval is opened, and the merchant submits evidence to uphold the original sale.

DISPUTE

A DISPUTE occurs when a payment is reversed by the payment method (card issuer) after a customer complaint. The end customer will receive money back, and the processor will then debit the merchant the equivalent amount. For card payments, this is also known as a chargeback.

status	Description
OPEN	Occurs when a payment has been disputed, and your processor account has debited.
ACCEPTED	Occurs when a disputed payment has been accepted - acknowledged as a fair dispute by the merchant.
CHALLENGED	If a merchant thinks that a dispute has been unfairly raised, they can challenge it. This event is sent when a merchant submits evidence to challenge a dispute, and uphold the original sale.
EXPIRED	Merchants only have a finite time window in which they can challenge a dispute. This status is set when that time window expires.
CANCELLED	When a dispute is withdrawn by the end customer who raised the initial dispute, the dispute status will be changed to .
WON	If a dispute has been successfully challenged by the merchant, the dispute status will be updated to WON. For some card flows, this is known as a chargeback reversal.
LOST	If a dispute has been unsuccessfully challenged, the dispute status will be updated to LOST.

PREARBITRATION

If a merchant successfully challenges a dispute, but the payment method (usually a card issuer) believes a further review is required, a PREARBITRATION dispute type will be opened. This is effectively an ‘appeal’ process.

status	Description
OPEN	If a dispute has been challenged, but is appealed, the dispute status will be updated to OPEN. For cards, this occurs if the card issuer does not feel the evidence was compelling enough.
WON	Occurs when the pre-arbitration is won by the merchant, confirming the dispute has been overturned.
LOST	Occurs when the pre-arbitration is lost by the merchant, confirming the original dispute will stand. This is sometimes known as a second chargeback.