adyen-openapi/yaml/TransactionService-v4.yaml

openapi: 3.1.0
servers:
- url: https://balanceplatform-api-live.adyen.com/btl/api/v4
  description: Live Environment
- url: https://balanceplatform-api-test.adyen.com/btl/api/v4
  description: Test Environment
info:
  title: Raise disputes API
  description: "Disputes API for Issuing that you can use to raise disputes on transactions\
    \ made with an Adyen-issued card. You can also add attachments as supporting information\
    \ for a raised dispute, update information about the dispute, submit the dispute\
    \ for a chargeback, or close the dispute.\n\n## Authentication\nYour Adyen contact\
    \ will provide your API credential and an API key. To connect to the API, add\
    \ an `X-API-Key` header with the API key as the value, for example:\n\n ```\n\
    curl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\"\
    \ \\\n...\n```\n\nAlternatively, you can use the username and password to connect\
    \ to the API using basic authentication. For example:\n\n```\ncurl\n-H \"Content-Type:\
    \ application/json\" \\\n-U \"ws@BalancePlatform.YOUR_BALANCE_PLATFORM\":\"YOUR_WS_PASSWORD\"\
    \ \\\n...\n```\n## Roles and permissions\nTo use the Disputes API, you need an\
    \ additional role for your API credential. Your Adyen contact will set up the\
    \ roles and permissions for you.\n## Versioning\nThe 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.\n\nFor example:\n```\nhttps://balanceplatform-api-test.adyen.com/btl/api/v{version}/disputes\n\
    ```\n## Going live\nWhen going live, your Adyen contact will provide your API\
    \ credential for the live environment. You can then use the username and password\
    \ to send requests to `https://balanceplatform-api-live.adyen.com/btl/api/v{version}`.\n\
    \n"
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
  version: '4'
  x-timestamp: '2025-02-26T15:35:55Z'
tags:
- name: Dispute Attachments
- name: Raise Disputes
paths:
  /disputes/{disputeId}/attachments:
    get:
      tags:
      - Dispute Attachments
      summary: Get all attachments linked to a raised dispute
      description: Get a list of attachments associated with a dispute ID.
      operationId: get-disputes-disputeId-attachments
      parameters:
      - name: disputeId
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DisputeAttachment'
      x-sortIndex: 2
    post:
      tags:
      - Dispute Attachments
      summary: Add an attachment to a dispute
      description: Add supporting information as an attachment for the raised dispute.
        Upload receipts, communication, or any other documentation to support the
        dispute.
      operationId: post-disputes-disputeId-attachments
      parameters:
      - name: disputeId
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeAttachment'
        required: true
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachDocumentResponse'
      x-sortIndex: 2
  /disputes/{disputeId}/attachments/{attachmentId}:
    get:
      tags:
      - Dispute Attachments
      summary: Get an attachment
      description: Search for a single attachment, providing the specific dispute
        ID and attachment ID.
      operationId: get-disputes-disputeId-attachments-attachmentId
      parameters:
      - name: disputeId
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      - name: attachmentId
        in: path
        description: The unique identifier of the attachment.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeAttachment'
      x-sortIndex: 2
    delete:
      tags:
      - Dispute Attachments
      summary: Delete attachment from a dispute
      description: Removes the attachment from the raised dispute. Adyen may keep
        this file for compliance purposes.
      operationId: delete-disputes-disputeId-attachments-attachmentId
      parameters:
      - name: disputeId
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      - name: attachmentId
        in: path
        description: The unique identifier of the attachment.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content - the request has been successfully processed, but
            there is no additional content.
          content:
            application/json: {}
      x-sortIndex: 2
  /disputes:
    get:
      tags:
      - Raise Disputes
      summary: Get a list of raised disputes
      description: 'Returns a list of raised disputes that match the query parameters.


        This endpoint supports cursor-based pagination. The response returns the first
        page of results, and returns links to the next page when applicable. You can
        use the links to page through the results. The response also returns links
        to the previous page when applicable.'
      operationId: get-disputes
      parameters:
      - name: status
        in: query
        description: 'The current status of the dispute.


          Possible values: **draft**, **submitted**, **closed**, **won**, **chargeback**,
          **secondPresentment**.'
        schema:
          type: string
      - name: paymentInstrument
        in: query
        description: The unique identifier of the payment instrument.
        schema:
          type: string
      - name: createdSince
        in: query
        description: Only include disputes that have been created on or after this
          point in time. The value must be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601\)  format.
          For example, 2021-05-30T15:07:40Z.
        schema:
          type: string
      - name: createdUntil
        in: query
        description: Only include disputes that have been created on or before this
          point in time. The value must be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601\)
          format. For example, **2021-05-30T15:07:40Z**.
        schema:
          type: string
      - name: offset
        in: query
        description: The number of items that you want to skip.
        schema:
          type: string
      - name: limit
        in: query
        description: The number of items returned per page, maximum of 500 items.
          By default, the response returns 100 items per page.
        schema:
          type: string
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DisputeResponse'
      x-sortIndex: 1
    post:
      tags:
      - Raise Disputes
      summary: Raise a dispute
      description: 'Raise a dispute for an underlying transaction, providing a dispute
        type and the amount you want to dispute.


        Raising a dispute returns a dispute ID, which you can use to update details
        about the dispute, provide supporting documentation, close the dispute, or
        submit the dispute for a chargeback. You can also use the dispute ID to view
        the status of the dispute.'
      operationId: post-disputes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeRequest'
        required: true
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
      x-sortIndex: 1
  /disputes/{id}:
    get:
      tags:
      - Raise Disputes
      summary: Get dispute by ID
      description: Get a raised dispute by ID.
      operationId: get-disputes-id
      parameters:
      - name: id
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
      x-sortIndex: 1
    patch:
      tags:
      - Raise Disputes
      summary: Update a raised dispute
      description: '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.'
      operationId: patch-disputes-id
      parameters:
      - name: id
        in: path
        description: The unique identifier of the raised dispute.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchableDisputeRequest'
      responses:
        '200':
          description: OK - the request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
      x-sortIndex: 1
components:
  schemas:
    AttachmentType:
      type: string
      enum:
      - receipt
      - correspondence
      - other
    DisputeAttachment:
      required:
      - attachmentType
      - content
      - fileName
      type: object
      properties:
        attachmentType:
          description: 'The type of information contained in the attachment: **receipt**,
            **correspondence**, **other**.'
          $ref: '#/components/schemas/AttachmentType'
        content:
          type: string
          description: The content of the image. An attachment must be base64-encoded
            data.
        fileName:
          maxLength: 17
          minLength: 4
          pattern: ([^\s]+(\.(?i)(jpeg|tiff|pdf))$)
          type: string
          description: 'The name of the attachment, including its filename extension.
            Supported filename extensions: **jpeg**, **pdf**, **tiff**.'
        id:
          type: string
          description: The unique identifier of the attachment.
          readOnly: true
    AttachDocumentResponse:
      type: object
      properties:
        attachmentId:
          type: string
          description: The unique identifier of the attachment.
          readOnly: true
    Amount:
      required:
      - currency
      - value
      type: object
      properties:
        currency:
          type: string
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes).
        value:
          type: integer
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).
          format: int64
    CancellingEntity:
      type: string
      enum:
      - merchant
      - cardholder
    DisputeRequest:
      required:
      - transactionId
      - type
      type: object
      properties:
        description:
          maxLength: 50
          minLength: 0
          type: string
          description: Your description for the dispute.
        disputedAmount:
          description: 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.
          $ref: '#/components/schemas/Amount'
        fraudInfo:
          description: Additional information for raising a dispute of `type` **fraud**.
            Required for disputes of `type` **fraud**.
          $ref: '#/components/schemas/FraudInfo'
        notDeliveredInfo:
          description: Additional information for raising a dispute of `type` **notDelivered**.
            Required for disputes of `type` **notDelivered**.
          $ref: '#/components/schemas/NotDeliveredInfo'
        status:
          description: 'The current status of the dispute.


            You can update a dispute to **submitted** or **closed**.


            Possible values: **draft**, **submitted**, **closed**, **won**, **chargeback**,
            **secondPresentment**.'
          $ref: '#/components/schemas/DisputeStatus'
        transactionId:
          type: string
          description: The unique reference of the transaction for which you are raising
            the dispute.
        type:
          description: 'The type of the dispute.


            Possible values: **notDelivered**, **fraud**.'
          $ref: '#/components/schemas/DisputeType'
    DisputeStatus:
      type: string
      enum:
      - draft
      - submitted
      - chargeback
      - secondPresentment
      - won
      - closed
    DisputeType:
      type: string
      x-extensible-enum:
      - notDelivered
      - fraud
    FraudInfo:
      required:
      - cardDoesNotBelongToCardholder
      - cardWasCounterfeited
      - descriptionOfIssue
      type: object
      properties:
        cardDoesNotBelongToCardholder:
          type: boolean
          description: The card is no longer in the cardholder's possession. Set to
            **true** if the card is lost or stolen.
        cardWasCounterfeited:
          type: boolean
          description: The card was counterfeited.
        descriptionOfIssue:
          maxLength: 2500
          minLength: 0
          type: string
          description: Your description of the issue for raising a dispute of `type`
            **fraud**.
        reportOnly:
          type: boolean
          description: 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**.
    NotDeliveredInfo:
      required:
      - descriptionOfIssue
      - lastExpectedDate
      - whatWasNotDelivered
      type: object
      properties:
        dateOfCancellation:
          type: string
          description: The date the undelivered goods or services were cancelled in
            YYYY-MM-DD format.
          format: date
        descriptionOfIssue:
          maxLength: 2500
          minLength: 0
          type: string
          description: Your description of the issue for raising a dispute of `type`
            **notDelivered**.
        lastExpectedDate:
          type: string
          description: The date the undelivered goods or services were expected to
            be delivered in YYYY-MM-DD format.
          format: date
        whatWasNotDelivered:
          description: 'The type of product that you expected to receive.


            Possible values: **goods**, **services**.'
          $ref: '#/components/schemas/ProductType'
        whoCancelled:
          description: 'The party that initiated the cancellation of the transaction.


            Possible values: **merchant**, **cardholder**.'
          $ref: '#/components/schemas/CancellingEntity'
    ProductType:
      type: string
      enum:
      - goods
      - services
    DisputeResponse:
      required:
      - transactionId
      - type
      type: object
      properties:
        arn:
          type: string
          description: 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.
          readOnly: true
        description:
          type: string
          description: Your description for the dispute.
        disputedAmount:
          description: 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.
          $ref: '#/components/schemas/Amount'
        fraudInfo:
          description: Additional information for raising a dispute of `type` **fraud**.
            Required for disputes of `type` **fraud**.
          $ref: '#/components/schemas/FraudInfo'
        id:
          type: string
          description: The unique identifier of the raised dispute.
          readOnly: true
        notDeliveredInfo:
          description: Additional information for raising a dispute of `type` **notDelivered**.
            Required for disputes of `type` **notDelivered**.
          $ref: '#/components/schemas/NotDeliveredInfo'
        status:
          description: 'The current status of the dispute.


            You can update a dispute to **submitted** or **closed**.


            Possible values: **draft**, **submitted**, **closed**, **won**, **chargeback**,
            **secondPresentment**.'
          $ref: '#/components/schemas/DisputeStatus'
        transactionId:
          type: string
          description: The unique reference of the transaction for which you are raising
            the dispute.
        type:
          description: 'The type of the dispute.


            Possible values: **notDelivered**, **fraud**.'
          $ref: '#/components/schemas/DisputeType'
    PatchableDisputeRequest:
      type: object
      properties:
        fraudInfo:
          type: object
          description: Additional information for raising a dispute of `type` **fraud**.
            Required for disputes of `type` **fraud**.
          oneOf:
          - $ref: '#/components/schemas/PatchableFraudInfo'
          - type: 'null'
        notDeliveredInfo:
          type: object
          description: Additional information for raising a dispute of `type` **notDelivered**.
            Required for disputes of `type` **notDelivered**.
          oneOf:
          - $ref: '#/components/schemas/PatchableNotDeliveredInfo'
          - type: 'null'
        status:
          type: object
          description: 'The current status of the dispute.


            You can update a dispute to **submitted** or **closed**.


            Possible values: **draft**, **submitted**, **closed**, **won**, **chargeback**,
            **secondPresentment**.'
          oneOf:
          - $ref: '#/components/schemas/DisputeStatus'
          - type: 'null'
    PatchableFraudInfo:
      type: object
      properties:
        cardDoesNotBelongToCardholder:
          type: boolean
          description: The card is no longer in the cardholder's possession. Set to
            **true** if the card is lost or stolen.
        cardWasCounterfeited:
          type: boolean
          description: The card was counterfeited.
        descriptionOfIssue:
          maxLength: 2500
          minLength: 0
          type: string
          description: Your description of the issue for raising a dispute of `type`
            **fraud**.
        reportOnly:
          type:
          - boolean
          - 'null'
          description: 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**.
    PatchableNotDeliveredInfo:
      type: object
      properties:
        dateOfCancellation:
          type:
          - string
          - 'null'
          description: The date the undelivered goods or services were cancelled in
            YYYY-MM-DD format.
          format: date
        descriptionOfIssue:
          maxLength: 2500
          minLength: 0
          type: string
          description: Your description of the issue for raising a dispute of `type`
            **notDelivered**.
        lastExpectedDate:
          type: string
          description: The date the undelivered goods or services were expected to
            be delivered in YYYY-MM-DD format.
          format: date
        whatWasNotDelivered:
          description: 'The type of product that you expected to receive.


            Possible values: **goods**, **services**.'
          $ref: '#/components/schemas/ProductType'
        whoCancelled:
          type: object
          description: 'The party that initiated the cancellation of the transaction.


            Possible values: **merchant**, **cardholder**.'
          oneOf:
          - $ref: '#/components/schemas/CancellingEntity'
          - type: 'null'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    BasicAuth:
      type: http
      scheme: basic
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base