What are disputes and chargebacks?
A dispute is an umbrella term for customers contacting their payment provider to request a transaction is reversed and receive their money back.
Online sellers will be notified by a payment processor when this occurs.
These notifications can be used to proactively communicate with customers, issue refunds, send disputes to risk tools, or to automatically defend disputes.
Sometimes chargeback and dispute can be used interchangeably - at Primer we use the more generic term of 'dispute' as 'chargeback' is usually associated with card payments only. Don't worry if you're looking for information on chargebacks - you're in the right place!
A dispute in Primer has:
- a dispute type and status that conforms to a unified dispute lifecycle
- information about the original payment submitted to Primer, such as payment method, order ID, and payment ID
The following currencies are not supported for dispute management:
BHD, BIF, CLP, CVE, GNF, HUF, IDR, INR, ISK, KHR, KMF, MMK, PYG, RWF, SAR, UGX, VED, VES, VND, XOF, XPF
If a dispute is received in one of these currencies no webhook will be triggered.
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.
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. |
Access your dispute information
Our DISPUTE.STATUS webhook will notify you when a dispute event has been received from the processor.
The webhook can be set up inside the Primer dashboard. If you want to know more about webhooks, check out our Webhook guide. For these webhooks to be sent from Primer, you also first have to set up dispute notifications to be sent to Primer from within the processor dashboard.
Primer Disputes app
The Primer Disputes app allows our unified disputes to be used in (Primer Workflows)[/automation].
When a new dispute is received from a processor, the dispute app can automate sharing the unified dispute format with other apps.
For example, this can be used to send dispute events to fraud tools like Riskified, who often require this information to improve risk models, or indemnify chargebacks.