mirror of
https://github.com/gcatanese/adyen-openapi.git
synced 2026-03-10 08:01:24 +00:00
682 lines
23 KiB
YAML
682 lines
23 KiB
YAML
openapi: 3.1.0
|
|
servers:
|
|
- url: https://ca-test.adyen.com/ca/services/DisputeService/v30
|
|
info:
|
|
version: '30'
|
|
x-publicVersion: true
|
|
title: 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.
|
|
|
|
|
|
## Authentication
|
|
|
|
Each request to the Disputes API must be signed with an API key. For this, obtain
|
|
an API Key from your Customer Area, as described in [How to get the API key](https://docs.adyen.com/development-resources/api-credentials#generate-api-key).
|
|
Then set this key to the `X-API-Key` header value, for example:
|
|
|
|
|
|
```
|
|
|
|
curl
|
|
|
|
-H "Content-Type: application/json" \
|
|
|
|
-H "X-API-Key: Your_API_key" \
|
|
|
|
...
|
|
|
|
```
|
|
|
|
Note that when going live, you need to generate new web service user credentials
|
|
to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
|
|
|
|
|
|
## Versioning
|
|
|
|
Disputes API supports [versioning](https://docs.adyen.com/development-resources/versioning)
|
|
using a version suffix in the endpoint URL. This suffix has the following format:
|
|
"vXX", where XX is the version number.
|
|
|
|
|
|
For example:
|
|
|
|
```
|
|
|
|
https://ca-test.adyen.com/ca/services/DisputeService/v30/defendDispute
|
|
|
|
```'
|
|
termsOfService: https://www.adyen.com/legal/terms-and-conditions
|
|
contact:
|
|
name: Adyen Developer Experience team
|
|
url: https://github.com/Adyen/adyen-openapi
|
|
tags:
|
|
- name: General
|
|
paths:
|
|
/acceptDispute:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: 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'
|
|
description: Bad Request - a problem reading or understanding the request.
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unauthorized - authentication required.
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Forbidden - insufficient permissions to process the request.
|
|
'422':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unprocessable Entity - a request validation error.
|
|
'500':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Internal Server Error - the server could not process the request.
|
|
/defendDispute:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: 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'
|
|
description: Bad Request - a problem reading or understanding the request.
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unauthorized - authentication required.
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Forbidden - insufficient permissions to process the request.
|
|
'422':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unprocessable Entity - a request validation error.
|
|
'500':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Internal Server Error - the server could not process the request.
|
|
/deleteDisputeDefenseDocument:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: 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'
|
|
description: Bad Request - a problem reading or understanding the request.
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unauthorized - authentication required.
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Forbidden - insufficient permissions to process the request.
|
|
'422':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unprocessable Entity - a request validation error.
|
|
'500':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Internal Server Error - the server could not process the request.
|
|
/retrieveApplicableDefenseReasons:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: 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'
|
|
description: Bad Request - a problem reading or understanding the request.
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unauthorized - authentication required.
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Forbidden - insufficient permissions to process the request.
|
|
'422':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unprocessable Entity - a request validation error.
|
|
'500':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Internal Server Error - the server could not process the request.
|
|
/supplyDefenseDocument:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: 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'
|
|
description: Bad Request - a problem reading or understanding the request.
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unauthorized - authentication required.
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Forbidden - insufficient permissions to process the request.
|
|
'422':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Unprocessable Entity - a request validation error.
|
|
'500':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServiceError'
|
|
description: Internal Server Error - the server could not process the request.
|
|
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.\n\nPossible values: \n\n* **Required**: You\
|
|
\ must supply the document.\n\n * **OneOrMore**: You must supply at least\
|
|
\ one of the documents with this label.\n\n* **Optional**: You can choose\
|
|
\ to supply the document.\n\n* **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
|