Primer Docs

💡

The "Dispute status update" Trigger can be used as the starting point for your dispute management workflows, and can be built to send updates to any third party services, or to automate refunds through the Payments app.

The "Dispute status update" Trigger will listen for dispute notifications sent by payment processors that have been added as payment connections in the Primer dashboard. All dispute notifications are mapped to the unified Primer framework, this Trigger works the same way regardless of the processor that originates the dispute.

Use cases

You can build workflows that react to new dispute events.

For example, you can have a dedicated workflow to send all new dispute events to a third-party fraud platform to benefit from dispute liability cover, and to help the fraud platform fine tune their risk decision engine.

You could also set up a separate workflow to automate the refund of payment where a retrieval dispute type is received, to prevent a dispute from being created later.

A retrieval signifies an investigation into a payment has been launched. Depending on the results of this investigation, a dispute may be raised, and the payment can be reversed. A dispute not only results in the amount of the payment being debited from your processor account, you are also liable to pay additional fees to the processor, so automating refunds when a retrieval notification is received can save time and money.

Output reference

Name	Type	Description
Dispute ID	string	A unique identifier for this dispute event generated by Primer. This is unique to each dispute event - so is not shared across various `type` and `status` relating to the same payment.
Processor dispute ID	string	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 `processorDisputeId`.
Processor	string	The payment processor that you submitted a payment to, and received a dispute notification from.
Date received	datetime	Date and time at which primer received the processor’s dispute event. Provided as an ISO timestamp in UTC.
Required response date	datetime	Time by which the merchant must challenge a dispute. This is provided by the processor, where available.
Type	enum: RETRIEVAL, DISPUTE, PREARBITRATION	The type of dispute event. More information on what the `type` field represents can be found in our manage disputes guide.
Order ID	string	Your reference for the sale transaction that the dispute relates to.
Merchant ID	string	The merchant ID registered at the payment processor used for this dispute.
Status	enum: OPEN, ACCEPTED, CHALLENGED, EXPIRED, CANCELLED, WON, LOST	To see which statuses are applicable for a dispute `type`, and how we map `status`, please see our manage disputes guide.
Reason code	string	The dispute reason code for a dispute. This will be the same code provided by the card schemes.
Processor reason	string	The dispute reason provided by the processor.
Amount	integer	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 code	enum	Currency Code for the disputed amount. The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.