Dispute lifecycle
Full dispute lifecycle updates are currently available for Adyen, Braintree, Checkout.com and PayPal. For other supported processors - currently Wordline Connect, Wordline 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 CANCELLED. |
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 prearbitration is won by the merchant, confirming the dispute has been overturned. |
LOST | Occurs when the prearbitration is lost by the merchant, confirming the original dispute will stand. This is sometimes known as a second chargeback. |