You can use the Disputes API to automate the dispute handling process so that you can respond to disputes and chargebacks as soon as they are initiated. The Disputes API lets you retrieve defense reasons, supply and delete defense documents, and accept or defend disputes.
openapi: 3.1.0
servers:
- url: https://ca-test.adyen.com/ca/services/DisputeService/v30
info:
version: '30'
x-publicVersion: true
title: Adyen Disputes API
description: >-
You can use the [Disputes
API](https://docs.adyen.com/risk-management/disputes-api) to automate the
dispute handling process so that you can respond to disputes and chargebacks
as soon as they are initiated. The Disputes API lets you retrieve defense
reasons, supply and delete defense documents, and accept or defend disputes.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: acceptDispute
- name: defendDispute
- name: deleteDisputeDefenseDocument
- name: retrieveApplicableDefenseReasons
- name: supplyDefenseDocument
paths:
/acceptDispute:
post:
tags:
- acceptDispute
summary: Adyen Accept a Dispute
description: Accepts a specific dispute.
x-addedInVersion: '1'
operationId: post-acceptDispute
x-sortIndex: 1
x-methodName: acceptDispute
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
accept-dispute:
$ref: '#/components/examples/post-acceptDispute-accept-dispute'
schema:
$ref: '#/components/schemas/AcceptDisputeRequest'
responses:
'200':
content:
application/json:
examples:
accept-dispute:
$ref: '#/components/examples/post-acceptDispute-accept-dispute-200'
schema:
$ref: '#/components/schemas/AcceptDisputeResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-acceptDispute400Example:
summary: Default post-acceptDispute 400 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-acceptDispute401Example:
summary: Default post-acceptDispute 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-acceptDispute403Example:
summary: Default post-acceptDispute 403 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-acceptDispute422Example:
summary: Default post-acceptDispute 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-acceptDispute500Example:
summary: Default post-acceptDispute 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/defendDispute:
post:
tags:
- defendDispute
summary: Adyen Defend a Dispute
description: Defends a specific dispute.
x-addedInVersion: '1'
operationId: post-defendDispute
x-sortIndex: 1
x-methodName: defendDispute
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
defend-dispute:
$ref: '#/components/examples/post-defendDispute-defend-dispute'
schema:
$ref: '#/components/schemas/DefendDisputeRequest'
responses:
'200':
content:
application/json:
examples:
defend-dispute:
$ref: '#/components/examples/post-defendDispute-defend-dispute-200'
schema:
$ref: '#/components/schemas/DefendDisputeResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-defendDispute400Example:
summary: Default post-defendDispute 400 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-defendDispute401Example:
summary: Default post-defendDispute 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-defendDispute403Example:
summary: Default post-defendDispute 403 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-defendDispute422Example:
summary: Default post-defendDispute 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-defendDispute500Example:
summary: Default post-defendDispute 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/deleteDisputeDefenseDocument:
post:
tags:
- deleteDisputeDefenseDocument
summary: Adyen Delete a Defense Document
description: Deletes a specific dispute defense document that was supplied earlier.
x-addedInVersion: '1'
operationId: post-deleteDisputeDefenseDocument
x-sortIndex: 1
x-methodName: deleteDisputeDefenseDocument
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
delete-dispute-defense-document:
$ref: >-
#/components/examples/post-deleteDisputeDefenseDocument-delete-dispute-defense-document
schema:
$ref: '#/components/schemas/DeleteDefenseDocumentRequest'
responses:
'200':
content:
application/json:
examples:
delete-dispute-defense-document:
$ref: >-
#/components/examples/post-deleteDisputeDefenseDocument-delete-dispute-defense-document-200
schema:
$ref: '#/components/schemas/DeleteDefenseDocumentResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-deleteDisputeDefenseDocument400Example:
summary: Default post-deleteDisputeDefenseDocument 400 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-deleteDisputeDefenseDocument401Example:
summary: Default post-deleteDisputeDefenseDocument 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-deleteDisputeDefenseDocument403Example:
summary: Default post-deleteDisputeDefenseDocument 403 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-deleteDisputeDefenseDocument422Example:
summary: Default post-deleteDisputeDefenseDocument 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-deleteDisputeDefenseDocument500Example:
summary: Default post-deleteDisputeDefenseDocument 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/retrieveApplicableDefenseReasons:
post:
tags:
- retrieveApplicableDefenseReasons
summary: Adyen Get Applicable Defense Reasons
description: >-
Returns a list of all applicable defense reasons to defend a specific
dispute.
x-addedInVersion: '1'
operationId: post-retrieveApplicableDefenseReasons
x-sortIndex: 1
x-methodName: retrieveApplicableDefenseReasons
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
retrieve-defense-reasons:
$ref: >-
#/components/examples/post-retrieveApplicableDefenseReasons-retrieve-defense-reasons
schema:
$ref: '#/components/schemas/DefenseReasonsRequest'
responses:
'200':
content:
application/json:
examples:
retrieve-defense-reasons:
$ref: >-
#/components/examples/post-retrieveApplicableDefenseReasons-retrieve-defense-reasons-200
schema:
$ref: '#/components/schemas/DefenseReasonsResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-retrieveApplicableDefenseReasons400Example:
summary: Default post-retrieveApplicableDefenseReasons 400 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-retrieveApplicableDefenseReasons401Example:
summary: Default post-retrieveApplicableDefenseReasons 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-retrieveApplicableDefenseReasons403Example:
summary: Default post-retrieveApplicableDefenseReasons 403 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-retrieveApplicableDefenseReasons422Example:
summary: Default post-retrieveApplicableDefenseReasons 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-retrieveApplicableDefenseReasons500Example:
summary: Default post-retrieveApplicableDefenseReasons 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/supplyDefenseDocument:
post:
tags:
- supplyDefenseDocument
summary: Adyen Supply a Defense Document
description: Supplies a specific dispute defense document.
x-addedInVersion: '1'
operationId: post-supplyDefenseDocument
x-sortIndex: 1
x-methodName: supplyDefenseDocument
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
supply-defense-document:
$ref: >-
#/components/examples/post-supplyDefenseDocument-supply-defense-document
schema:
$ref: '#/components/schemas/SupplyDefenseDocumentRequest'
responses:
'200':
content:
application/json:
examples:
supply-defense-document:
$ref: >-
#/components/examples/post-supplyDefenseDocument-supply-defense-document-200
schema:
$ref: '#/components/schemas/SupplyDefenseDocumentResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-supplyDefenseDocument400Example:
summary: Default post-supplyDefenseDocument 400 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-supplyDefenseDocument401Example:
summary: Default post-supplyDefenseDocument 401 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-supplyDefenseDocument403Example:
summary: Default post-supplyDefenseDocument 403 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-supplyDefenseDocument422Example:
summary: Default post-supplyDefenseDocument 422 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-supplyDefenseDocument500Example:
summary: Default post-supplyDefenseDocument 500 response
x-microcks-default: true
value:
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
AcceptDisputeRequest:
properties:
disputePspReference:
description: The PSP reference assigned to the dispute.
type: string
merchantAccountCode:
description: >-
The merchant account identifier, for which you want to process the
dispute transaction.
type: string
required:
- merchantAccountCode
- disputePspReference
type: object
AcceptDisputeResponse:
properties:
disputeServiceResult:
description: The result of the dispute service.
$ref: '#/components/schemas/DisputeServiceResult'
required:
- disputeServiceResult
type: object
DefendDisputeRequest:
properties:
defenseReasonCode:
description: The defense reason code that was selected to defend this dispute.
type: string
disputePspReference:
description: The PSP reference assigned to the dispute.
type: string
merchantAccountCode:
description: >-
The merchant account identifier, for which you want to process the
dispute transaction.
type: string
required:
- merchantAccountCode
- disputePspReference
- defenseReasonCode
type: object
DefendDisputeResponse:
properties:
disputeServiceResult:
description: The result of the dispute service.
$ref: '#/components/schemas/DisputeServiceResult'
required:
- disputeServiceResult
type: object
DefenseDocument:
properties:
content:
description: The content of the defense document.
format: byte
type: string
contentType:
description: The content type of the defense document.
type: string
defenseDocumentTypeCode:
description: The document type code of the defense document.
type: string
required:
- defenseDocumentTypeCode
- contentType
- content
type: object
DefenseDocumentType:
properties:
available:
description: >-
When **true**, you've successfully uploaded this type of defense
document. When **false**, you haven't uploaded this defense document
type.
type: boolean
defenseDocumentTypeCode:
description: The document type code of the defense document.
type: string
requirementLevel:
description: >-
Indicates to what extent the defense document is required in the
defense process.
Possible values:
* **Required**: You must supply the document.
* **OneOrMore**: You must supply at least one of the documents with this label.
* **Optional**: You can choose to supply the document.
* **AlternativeRequired**: You must supply a generic defense
document. To enable this functionality, contact our Support Team.
When enabled, you can supply a generic defense document for all
schemes.
type: string
required:
- defenseDocumentTypeCode
- requirementLevel
- available
type: object
DefenseReason:
properties:
defenseDocumentTypes:
description: >-
Array of defense document types for a specific defense reason.
Indicates the document types that you can submit to the schemes to
defend this dispute, and whether they are required.
items:
$ref: '#/components/schemas/DefenseDocumentType'
type: array
defenseReasonCode:
description: The defense reason code that was selected to defend this dispute.
type: string
satisfied:
description: Indicates if sufficient defense material has been supplied.
type: boolean
required:
- defenseReasonCode
- satisfied
type: object
DefenseReasonsRequest:
properties:
disputePspReference:
description: The PSP reference assigned to the dispute.
type: string
merchantAccountCode:
description: >-
The merchant account identifier, for which you want to process the
dispute transaction.
type: string
required:
- merchantAccountCode
- disputePspReference
type: object
DefenseReasonsResponse:
properties:
defenseReasons:
description: The defense reasons that can be used to defend the dispute.
items:
$ref: '#/components/schemas/DefenseReason'
type: array
disputeServiceResult:
description: The result of the dispute service.
$ref: '#/components/schemas/DisputeServiceResult'
required:
- disputeServiceResult
type: object
DeleteDefenseDocumentRequest:
properties:
defenseDocumentType:
description: The document type code of the defense document.
type: string
disputePspReference:
description: The PSP reference assigned to the dispute.
type: string
merchantAccountCode:
description: >-
The merchant account identifier, for which you want to process the
dispute transaction.
type: string
required:
- merchantAccountCode
- disputePspReference
- defenseDocumentType
type: object
DeleteDefenseDocumentResponse:
properties:
disputeServiceResult:
description: The result of the dispute service.
$ref: '#/components/schemas/DisputeServiceResult'
required:
- disputeServiceResult
type: object
DisputeServiceResult:
properties:
errorMessage:
description: The general error message.
type: string
success:
description: Indicates whether the request succeeded.
type: boolean
required:
- success
type: object
ServiceError:
properties:
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
type: object
SupplyDefenseDocumentRequest:
properties:
defenseDocuments:
description: An array containing a list of the defense documents.
items:
$ref: '#/components/schemas/DefenseDocument'
type: array
disputePspReference:
description: The PSP reference assigned to the dispute.
type: string
merchantAccountCode:
description: >-
The merchant account identifier, for which you want to process the
dispute transaction.
type: string
required:
- merchantAccountCode
- disputePspReference
- defenseDocuments
type: object
SupplyDefenseDocumentResponse:
properties:
disputeServiceResult:
description: The result of the dispute service.
$ref: '#/components/schemas/DisputeServiceResult'
required:
- disputeServiceResult
type: object
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
examples:
post-acceptDispute-accept-dispute:
summary: Accept a dispute
value:
disputePspReference: DZ4DPSHB4WD2WN82
merchantAccountCode: YOUR_MERCHANT_ACCOUNT
post-acceptDispute-accept-dispute-200:
summary: Dispute accepted
value:
disputeServiceResult:
success: true
post-defendDispute-defend-dispute:
summary: Defend a dispute
value:
defenseReasonCode: SupplyDefenseMaterial
disputePspReference: DZ4DPSHB4WD2WN82
merchantAccountCode: YOUR_MERCHANT_ACCOUNT
post-defendDispute-defend-dispute-200:
summary: Dispute defended
value:
disputeServiceResult:
success: true
post-deleteDisputeDefenseDocument-delete-dispute-defense-document:
summary: Delete a dispute defense document
value:
defenseDocumentType: DefenseMaterial
disputePspReference: DZ4DPSHB4WD2WN82
merchantAccountCode: YOUR_MERCHANT_ACCOUNT
post-deleteDisputeDefenseDocument-delete-dispute-defense-document-200:
summary: Dispute defense document deleted
value:
disputeServiceResult:
success: true
post-retrieveApplicableDefenseReasons-retrieve-defense-reasons:
summary: Retrieve applicable defense reasons
value:
disputePspReference: DZ4DPSHB4WD2WN82
merchantAccountCode: YOUR_MERCHANT_ACCOUNT
post-retrieveApplicableDefenseReasons-retrieve-defense-reasons-200:
summary: Applicable dispute defense reasons retrieved
value:
defenseReasons:
- defenseDocumentTypes:
- available: false
defenseDocumentTypeCode: TIDorInvoice
requirementLevel: Optional
- available: false
defenseDocumentTypeCode: GoodsNotReturned
requirementLevel: Required
defenseReasonCode: GoodsNotReturned
satisfied: false
- defenseDocumentTypes:
- available: false
defenseDocumentTypeCode: TIDorInvoice
requirementLevel: Optional
- available: false
defenseDocumentTypeCode: GoodsRepairedOrReplace
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/disputes-openapi-original.yml