Issuin icon

Manage disputes

Edit information about a dispute, and submit or close a raised dispute.

When a dispute has a status of draft, you can edit the information associated with the dispute, and change the status of the dispute to submitted or closed. You can also provide supporting information as attachments for the dispute.

Edit dispute information

To update information in your dispute, make a PATCH /disputes/{id} request, specifying the dispute id as a path parameter, and supplying updated information in the following request parameters:

Parameter Type Description
fraudInfo object The object containing additional information for raising a dispute of type fraud. Required for disputes of type fraud.
fraudInfo.cardDoesNotBelongToCardholder boolean The card is no longer in the cardholder's possession. Set to true if the card is lost or stolen. Possible values: true, false.
fraudInfo.cardWasCounterfeited boolean The card was counterfeited. Possible values: true, false.
fraudInfo.descriptionOfIssue string Your description of the issue for raising a dispute of type fraud. Maximum length, 2500 characters.
fraudInfo.reportOnly boolean Set to true to instruct Adyen to submit a report of fraud dispute with no further action, such as a request for a chargeback or fee reversal. The default value is false.
status string The status of the dispute. You can update the status of a raised dispute from draft to submitted or closed. Possible values: submitted, closed.

Submit a dispute

  1. Make a PATCH /disputes/{id} request, specifying the dispute id as a path parameter, and include status with a value of submitted as a request parameter.

    Change the status of a dispute to submitted
    Expand view
    Copy link to code block
    Copy code
    Copy code
    		curl https://balanceplatform-api-test.adyen.com/btl/api/v4/disputes/4VXM2M64Q6OL1111 \
    		-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
    		-H 'content-type: application/json' \
    		-X PATCH  \
    		-d '{ 
    		       "status": "submitted"
    		}'

  2. A successful response includes the dispute object, with an updated status of submitted. Adyen also sends your system a balancePlatform.dispute.updated webhook with the updated status.

    Dispute webhook with a status of submitted
    Expand view
    Copy link to code block
    Copy code
    Copy code
    		{
    		  "data": {
    		    "balancePlatform": "MyBalancePlatform",
    		    "id": "4VXM2M64Q6OL1111",
    		    "description": "MyCompanyReference-456-555543-0009",
    		    "disputedAmount": {
    		      "currency": "USD",
    		      "value": 12500
    		    },
    		    "type": "notDelivered",
    		    "transactionId": "EVJN42BZX224223N5LJ3ZHP4N11111USD",
    		    "status": "submitted",
    		    "arn": "74987504296002007652011"
    		  },
    		  "environment": "test",
    		  "type": "balancePlatform.dispute.updated"
    		}

  3. Notify your cardholder that they have successfully submitted their dispute.

Close a dispute

You can change the status of a dispute to closed when you no longer intend to submit the dispute. You can only close a dispute whose status is draft.

After you close a dispute, you cannot edit, submit, or reopen that dispute.

  1. Make a PATCH /disputes/{id} request, specifying the dispute id as a path parameter, and include status with a value of closed as a request parameter.

    Change the status of a dispute to closed
    Expand view
    Copy link to code block
    Copy code
    Copy code
    		curl https://balanceplatform-api-test.adyen.com/btl/api/v4/disputes/5UTH6M64Q6OL0076 \
    		-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
    		-H 'content-type: application/json' \
    		-X PATCH  \
    		-d '{ 
    		       "status": "closed"
    		}'

  2. A successful response includes the dispute object, with an updated status of closed. Adyen also sends your system a balancePlatform.dispute.updated webhook with the updated status.

    Dispute webhook with a status of closed
    Expand view
    Copy link to code block
    Copy code
    Copy code
    		{
    		  "data": {
    		    "balancePlatform": "MyBalancePlatform",
    		    "id": "4VXM2M64Q6OL1111",
    		    "description": "MyCompanyReference-456-555543-0009",
    		    "disputedAmount": {
    		      "currency": "USD",
    		      "value": 12500
    		    },
    		    "type": "notDelivered",
    		    "transactionId": "EVJN42BZX224223N5LJ3ZHP4N11111USD",
    		    "status": "closed",
    		    "arn": "74987504296002007652011"
    		  },
    		  "environment": "test",
    		  "type": "balancePlatform.dispute.updated"
    		}

  3. Notify your cardholder that they have successfully closed their dispute.

See also