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: GoodsRepairedOrReplaced requirementLevel: Required defenseReasonCode: GoodsRepairedOrReplaced satisfied: false - defenseDocumentTypes: - available: false defenseDocumentTypeCode: GoodsWereAsDescribed requirementLevel: Required - available: false defenseDocumentTypeCode: TIDorInvoice requirementLevel: Required defenseReasonCode: GoodsWereAsDescribed satisfied: false - defenseDocumentTypes: - available: false defenseDocumentTypeCode: TIDorInvoice requirementLevel: Optional - available: false defenseDocumentTypeCode: DefenseMaterial requirementLevel: Required defenseReasonCode: SupplyDefenseMaterial satisfied: false disputeServiceResult: success: true post-supplyDefenseDocument-supply-defense-document: summary: Supply dispute defense documents value: defenseDocuments: - content: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv+f/ub0j6JPRX+E3EmC== contentType: application/pdf defenseDocumentTypeCode: DefenseMaterial disputePspReference: DZ4DPSHB4WD2WN82 merchantAccountCode: YOUR_MERCHANT_ACCOUNT post-supplyDefenseDocument-supply-defense-document-200: summary: Dispute defense documents supplied value: disputeServiceResult: success: true