Update a raised dispute

patch/disputes/{id}

Update information related to a raised dispute, or change a dispute's status from draft to submitted or closed.

Note: Changing the status of a dispute to submitted or closed is a final action. You cannot make updates to a submitted or closed dispute. Make sure to upload all supporting attachments using the POST /disputes/{id}/attachments endpoint before you submit a dispute. When you update a dispute to submitted, Adyen sends the raised dispute to the card scheme for review and acquirer defense. When you update a raised dispute to closed, Adyen closes the dispute, and the dispute is no longer eligible for review by the card scheme.

Endpoint destination URL

Path Parameters

Required

Optional

The unique identifier of the raised dispute.

Request Parameters

Required

Optional

Additional information for raising a dispute of type cancelled. Required for disputes of type cancelled.

Additional information for raising a dispute of type duplicate. Required for disputes of type duplicate.

Additional information for raising a dispute of type fraud. Required for disputes of type fraud.

Additional information for raising a dispute of type notAsDescribed. Required for disputes of type notAsDescribed.

Additional information for raising a dispute of type notDelivered. Required for disputes of type notDelivered.

Additional information for raising a dispute of type other. Required for disputes of type other.

Note: The other dispute type is deprecated. Do not create or submit any disputes for this dispute type.

The current status of the dispute.

When you create a dispute, you can only set the status to draft. When you update a dispute, you can set the status to submitted or closed.

Possible values: draft, submitted, closed, won, chargeback, secondPresentment.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
arnstring
The unique Acquirer Reference Number (arn) generated by the card scheme for each capture. You can use the arn to trace the transaction through its lifecycle.
cancelledInfoobject
Additional information for raising a dispute of type cancelled. Required for disputes of type cancelled.
attemptedToReturnboolean
Indicates if the cardholder attempted to return the merchandise but was unable to.

Possible values: true, false.

Required if the value of didCardholderReturn is false.

If the value of this parameter is true, provide information in descriptionOfIssue about how the cardholder attempted to return the goods, and what they did with the goods (for example, destroyed them).
certificationGuaranteedReservationstring
The certification code for the guaranteed reservation.

Required if the value of serviceType is guaranteedReservation (a guaranteed reservation).

Possible values:

GR: The cardholder properly cancelled the guaranteed reservation.

RC: The cardholder attempted to cancel within 24 hours of delivery of the reservation confirmation.

AR: The merchant billed a "no-show transaction" for more than one day's accommodation or rental.

dateOfAttemptedReturnstring
The date, in YYYY-MM-DD format, when the cardholder attempted to return the goods they purchased.

Required if the value of attemptedToReturn is true.
dateOfCancellationstring
The date, in YYYY-MM-DD format, when the purchase was cancelled.

Required if the value of certificationGuaranteedReservation is GR or RC, or if the value of didCardholderCancelBeforeShipment is true.
dateOfReturnstring
The date, in YYYY-MM-DD format, that the cardholder shipped or handed back the merchandise.

Required if the value of didCardholderReturn is true.
dateOfServicestring
The date, in YYYY-MM-DD format, that the service was scheduled to take place.

Required if the value of serviceType is other (any other type of service) or guaranteedReservation (a guaranteed reservation).
dateReturnReceivedstring
The date, in YYYY-MM-DD format, that the merchant received the returned merchandise.

Required if the value of didCardholderReturn is true.
descriptionOfIssuestring
Max length: 2500
Your description of the issue for raising a dispute of type cancelled. Make sure the cardholder provides information that covers the following:

A description of the goods or services purchased, and why they are cancelling the purchase.

If the goods or services were cancelled before shipment: A description of how the cardholder attempted to cancel the goods or services.

If the cardholder attempted to return the goods: A description of how the cardholder attempted to return the goods, and what they did with the goods (for example, destroyed them).

If the cardholder attempted to return the goods in a way other than through direct return shipment or face-to-face return at a merchant, how they attempted to return the goods.

Not required if the value of goodsOrServices is services, the value of serviceType is timeshare or guaranteedReservation, and the value of didCardholderCancelBeforeShipment is false.
didCardholderCancelBeforeShipmentboolean
Indicates if the cardholder cancelled the purchase before the goods were shipped.

Possible values: true, false.

If the value of this parameter is true, provide information in descriptionOfIssue about how the cardholder attempted to cancel the goods or services.
didCardholderReceiveGoodsboolean
Indicates if the cardholder received the merchandise.

Possible values: true, false.

Required if the value of goodsOrServices is goods.
didCardholderReturnboolean
Indicates if the cardholder returned the merchandise to the merchant.

Possible values: true, false.

Required if the value of didCardholderReceiveGoods is true.
goodsOrServicesstring
The type of purchase being disputed.

Possible values: goods, services.
lastExpectedDatestring
The date, in YYYY-MM-DD format, that the merchant promised delivery.

Required if the value of goodsOrServices is goods.
merchantRefuseAdvisestring
The reason the merchant gave for refusing the return.

Required if the value of attemptedToReturn is true.

Possible values:

MRRA: The merchant refused to provide return authorization.

MRRM: The merchant refused to accept returned merchandise.

MICNRM: The merchant informed cardholder not to return the merchandise.

returnMethodstring
The method used to return the merchandise.

Required if the value of didCardholderReturn is true.

Possible values: faceToFace, fedEx, dhl, ups, postalService, other.

If the value of this parameter is other, or if the cardholder attempted a return but did not complete it, provide information in descriptionOfIssue about how the cardholder attempted to return the goods or services.
serviceTypestring
The type of service purchased.

Required if the value of goodsOrServices is services.

Possible values:

timeshare: A reservation for a timeshare.

guaranteedReservation: A guaranteed reservation (for example, a hotel or a car rental booking).

other: Any other type of service.

shippingTrackingNumberstring
Max length: 50
The tracking number for the shipment used to return the merchandise.
timeshareDatestring
The date, in YYYY-MM-DD format, associated with the timeshare purchase.

Required if the value of serviceType is timeshare.
wasCancellationPolicyProvidedboolean
Indicates if the merchant provided the cardholder with a cancellation policy.

Possible values: true, false.

Required if the value of didCardholderReceiveGoods is false, the value of didCardholderCancelBeforeShipment is true, or the value of serviceType is guaranteedReservation.
whoCancelledstring
The party that initiated the cancellation of the purchase.

Required if the value of serviceType is timeshare (a timeshare) or other (any other type of service), or if the value of didCardholderReceiveGoods is false.

Possible values: merchant, cardholder.
descriptionstring
Your description for the dispute.
disputedAmountobject
The amount for which you dispute the transaction. The disputed amount cannot be greater than the transaction amount. If you do not provide an amount, the entire transaction amount will be disputed.
currencystring
The three-character ISO currency code of the amount.
valueinteger
The numeric value of the amount, in minor units.
duplicateInfoobject
Additional information for raising a dispute of type duplicate. Required for disputes of type duplicate.
duplicateTransactionIdstring
Min length: 1
The transaction id associated with the duplicate charge for which you are disputing. The disputed transaction must be in the same amount as the duplicate transaction.
sameCardboolean
The duplicate charge was made on the same card. Possible values: true, false.
sameIssuerboolean
The issuer associated with each charge is the same. Possible values: true, false.
fraudInfoobject
Additional information for raising a dispute of type fraud. Required for disputes of type fraud.
cardDoesNotBelongToCardholderboolean
The card is no longer in the cardholder's possession. Set to true if the card is lost or stolen.
cardWasCounterfeitedboolean
The card was counterfeited.
descriptionOfIssuestring
Max length: 2500
Your description of the issue for raising a dispute of type fraud.
reportOnlyboolean
Set to true to report fraud to Adyen with no further action, such as a request for a chargeback or fee reversal. The default value is false.
idstring
The unique identifier of the raised dispute.
notAsDescribedInfoobject
Additional information for raising a dispute of type notAsDescribed. Required for disputes of type notAsDescribed.
attemptedToReturnboolean
Indicates if the cardholder attempted to return the merchandise, but was unsuccessful. Required if the value of didCardholderReturn is false.

Possible values: true, false.

If the value of this parameter is true, provide information in descriptionOfIssue about how the cardholder attempted to return the merchandise and what happened to the merchandise when the return was unsuccessful.
dateAttemptedToReturnstring
The date, in YYYY-MM-DD format, when the cardholder attempted to return the merchandise. Required if the value of attemptedToReturn is true.
dateOfCancellationstring
The date, in YYYY-MM-DD format, when the goods or services were cancelled by the cardholder. Required if the value of whoCancelled is cardholder.
dateOfFirstNegotiationsstring
The date, in YYYY-MM-DD format, that negotiations with the merchant began. Required if the value of evidenceOfNegotiationsWithMerchant is true.
dateOfReturnstring
The date, in YYYY-MM-DD format, when the cardholder shipped or handed back the merchandise to the merchant. Required if the value of didCardholderReturn is true.
dateReturnReceivedstring
The date, in YYYY-MM-DD format, when the merchant received the returned merchandise. Required if the value of didCardholderReturn is true.
descriptionOfIssuestring
Max length: 2500
Your description of the issue for raising a dispute of type notAsDescribed. Make sure the cardholder provides information that covers the following:

A description of the goods or services purchased, and why they did not fit the description of what they thought they purchased.

If the cardholder cancelled services that they purchased: A description of how the services were cancelled.

If the cardholder attempted to negotiate a resolution: A description of the negotiations that took place with the merchant.

If the goods or services were cancelled before shipment: A description of how the cardholder attempted to cancel the goods or services.

If the cardholder attempted to return the goods: A description of how the cardholder attempted to return the goods and what they did with the goods (for example, destroyed them).

didAttemptToResolveboolean
Indicates if the cardholder attempted to resolve the issue directly with the merchant before raising the dispute.

Possible values: true, false.
didCardholderReturnboolean
Indicates if the cardholder returned the merchandise to the merchant. Required if the value of goodsOrServices is goods, or if the value of disputeDueTo is defectiveMerchandise.

Possible values: true, false.
didMerchantAcceptCancellationboolean
Indicates if the merchant accepted the cancellation. Required if the cardholder cancelled the service within 15 days of the current date.

Possible values: true, false.
disputeDueTostring
Indicates the kind of dispute being raised by the cardholder.

Possible values: notAsDescribed, defectiveMerchandise.
evidenceOfNegotiationsWithMerchantboolean
Indicates if the cardholder attempted to negotiate a resolution with the merchant before raising the dispute. Required if more than 120 days have passed since both the lastExpectedDate and the transaction processing date.

Possible values: true, false.

If the value of this parameter is true, provide information in descriptionOfIssue about the negotiations that took place with the merchant.
goodsOrServicesstring
The type of purchase being disputed. Required if the value of disputeDueTo is notAsDescribed.

Possible values: goods, services.
isNonFiatOrNftboolean
Indicates if the transaction is non-fiat or non-fungible token (NFT) related. Required if the value of goodsOrServices is services.

Possible values: true, false.
lastExpectedDatestring
The date, in YYYY-MM-DD format, that the merchant promised delivery of the goods or services.
reasonMerchantRefusedstring
The reason the merchant gave for refusing the return. Required if the value of attemptedToReturn is true.

Possible values:

MRRA: The merchant refused to provide return authorization.

MRRM: The merchant refused to accept the returned merchandise.

MICNRM: The merchant told the cardholder not to return the merchandise.

MNLER: The merchant no longer exists or is not responding.

MNPCIR: The merchant did not provide clear instructions on how to return the merchandise.

resolutionProhibitedByLawboolean
Indicates if local law prohibits the cardholder from attempting to resolve the issue with the merchant. Required if the value of didAttemptToResolve is false. If this value is also false, the dispute cannot proceed.

Possible values: true, false.
returnMethodstring
The method used to return the merchandise. Required if the value of didCardholderReturn is true.

Possible values: faceToFace, fedEx, dhl, ups, postalService, other.

If the value of this parameter is other, provide information in descriptionOfIssue about how the merchandise was returned.
shippingTrackingNumberstring
Max length: 50
The tracking number for the shipment used to return the merchandise.
whoCancelledstring
The party that initiated cancellation of the service. Required if the value of goodsOrServices is services.

Possible values: merchant, cardholder.

If the value of this parameter is cardholder, provide information in descriptionOfIssue about how the service was cancelled.
notDeliveredInfoobject
Additional information for raising a dispute of type notDelivered. Required for disputes of type notDelivered.
agreedDeliveryLocationstring
Max length: 500
The delivery location specified by the cardholder. Required if deliveredToWrongLocation is true.
dateOfCancellationstring
The date the undelivered goods or services were cancelled in YYYY-MM-DD format.
deliveredToWrongLocationboolean
Indicates goods were delivered to the wrong location.

Possible values: true, false.
descriptionOfIssuestring
Max length: 2500
Your description of the issue for raising a dispute of type notDelivered.
didCardholderReturnboolean
Indicates if the cardholder returned the goods to the merchant. Required if isDeliveryLate is true.

Possible values: true, false.
isDeliveryLateboolean
Indicates if the goods or services were delivered late. Required if whatWasNotDelivered is goods.

Possible values: true, false.
isMerchantBankruptboolean
Indicates if the transaction was processed by a bankrupt merchant.

Possible values: true, false.
isNonFiatOrNftboolean
Indicates if the transaction is non-fiat or non-fungible token (NFT) related.

Possible values: true, false.
lastExpectedDatestring
The date the undelivered goods or services were expected to be delivered in YYYY-MM-DD format.
whatWasNotDeliveredstring
The type of product that you expected to receive.

Possible values: goods, services.
whoCancelledstring
The party that initiated the cancellation of the transaction.

Possible values: merchant, cardholder.
otherInfoobject
Additional information for raising a dispute of type other. Required for disputes of type other.

Note: The other dispute type is deprecated. Do not create or submit any disputes for this dispute type.
descriptionOfIssuestring
Max length: 2500
Your description of the issue for raising a dispute of type other.
subTypestring
The specific category of other dispute that you are raising.

Possible values: atmDispute, cancelledGoodsServices, cancelledRecurring, counterfeit, creditNotProcessed, notAsDescribed.
whatWasPurchasedstring
The type of product that you purchased.

Possible values: goods, services.
statusstring
The current status of the dispute.

When you create a dispute, you can only set the status to draft. When you update a dispute, you can set the status to submitted or closed.

Possible values: draft, submitted, closed, won, chargeback, secondPresentment.
transactionIdstring
The unique reference of the transaction for which you are raising the dispute.
typestring
The type of the dispute.

Possible values: cancelled, duplicate, fraud, notAsDescribed, notDelivered, other.

Note: The other dispute type is deprecated. Do not create or submit any disputes for this dispute type.
401
Authentication required.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
403
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.
422
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
Unique business error code.
instancestring
A URI that identifies the specific occurrence of the problem if applicable.
invalidFieldsarray[object]
Array of fields with validation errors when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
The unique reference for the request.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the validation error type. It points to human-readable documentation for the problem type.

Update a raised dispute

HTTP Responses

200 - OK

401

403

422