openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Cancels API
  description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\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 ```\ncurl\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-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account 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://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
  x-timestamp: '2023-05-30T15:27:20Z'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Cancels
paths:
  /cancels:
    post:
      tags:
      - Cancels
      summary: Adyen Cancel an Authorised Payment
      description: 'Cancels the authorisation on a payment that has not yet been [captured](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/captures), and returns a unique reference for this request. You get the outcome of the request asynchronously, in a [**TECHNICAL_CANCEL** webhook](https://docs.adyen.com/online-payments/cancel#cancellation-webhook).


        If you want to cancel a payment using the [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference), use the [`/payments/{paymentPspReference}/cancels`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/cancels) endpoint instead.


        If you want to cancel a payment but are not sure whether it has been captured, use the [`/payments/{paymentPspReference}/reversals`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/reversals) endpoint instead.


        For more information, refer to [Cancel](https://docs.adyen.com/online-payments/cancel).'
      operationId: post-cancels
      x-sortIndex: 3
      x-methodName: cancelAuthorisedPayment
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              cancel-with-own-reference:
                $ref: '#/components/examples/post-cancels-cancel-with-own-reference'
            schema:
              $ref: '#/components/schemas/StandalonePaymentCancelRequest'
      parameters:
      - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '201':
          content:
            application/json:
              examples:
                cancel-with-own-reference:
                  $ref: '#/components/examples/post-cancels-cancel-with-own-reference-201'
              schema:
                $ref: '#/components/schemas/StandalonePaymentCancelResponse'
          description: Created - the request has been fulfilled and has resulted in one or more new resources being created.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '400':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-400'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unprocessable Entity - a request validation error.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/cancel:
    post:
      tags:
      - Cancels
      summary: Adyen Cancel an Order
      description: Cancels an order. Cancellation of an order results in an automatic rollback of all payments made in the order, either by canceling or refunding the payment, depending on the type of payment method.
      operationId: post-orders-cancel
      x-sortIndex: 3
      x-methodName: cancelOrder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              basic:
                $ref: '#/components/examples/post-orders-cancel-basic'
            schema:
              $ref: '#/components/schemas/CancelOrderRequest'
      parameters:
      - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '200':
          content:
            application/json:
              examples:
                basic:
                  $ref: '#/components/examples/post-orders-cancel-basic-200'
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
          description: OK - the request has succeeded.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '400':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-400'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unprocessable Entity - a request validation error.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payments/{paymentPspReference}/cancels:
    post:
      tags:
      - Cancels
      summary: Adyen Cancel an Authorised Payment
      description: 'Cancels the authorisation on a payment that has not yet been [captured](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/paymentPspReference/captures), and returns a unique reference for this request. You get the outcome of the request asynchronously, in a [**CANCELLATION** webhook](https://docs.adyen.com/online-payments/cancel#cancellation-webhook).


        If you want to cancel a payment but don''t have the [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference), use the [`/cancels`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/cancels) endpoint instead.


        If you want to cancel a payment but are not sure whether it has been captured, use the [`/payments/{paymentPspReference}/reversals`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/reversals) endpoint instead.


        For more information, refer to [Cancel](https://docs.adyen.com/online-payments/cancel).'
      operationId: post-payments-paymentPspReference-cancels
      x-sortIndex: 2
      x-methodName: cancelAuthorisedPaymentByPspReference
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              cancel-with-psp-reference:
                $ref: '#/components/examples/post-payments-paymentPspReference-cancels-cancel-with-psp-reference'
            schema:
              $ref: '#/components/schemas/PaymentCancelRequest'
      parameters:
      - description: 'The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment that you want to cancel. '
        name: paymentPspReference
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '201':
          content:
            application/json:
              examples:
                cancel-with-psp-reference:
                  $ref: '#/components/examples/post-payments-paymentPspReference-cancels-cancel-with-psp-reference-201'
              schema:
                $ref: '#/components/schemas/PaymentCancelResponse'
          description: Created - the request has been fulfilled and has resulted in one or more new resources being created.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '400':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-400'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-401'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-403'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-422'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unprocessable Entity - a request validation error.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
        '500':
          content:
            application/json:
              examples:
                generic:
                  $ref: '#/components/examples/generic-500'
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PaymentCancelResponse:
      properties:
        merchantAccount:
          description: The merchant account that is used to process the payment.
          type: string
        paymentPspReference:
          description: 'The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment to cancel. '
          type: string
        pspReference:
          description: Adyen's 16-character reference associated with the cancel request.
          type: string
        reference:
          description: Your reference for the cancel request.
          type: string
        status:
          description: The status of your request. This will always have the value **received**.
          enum:
          - received
          type: string
      required:
      - status
      - merchantAccount
      - paymentPspReference
      - pspReference
      type: object
    CancelOrderRequest:
      properties:
        merchantAccount:
          description: The merchant account identifier that orderData belongs to.
          type: string
        order:
          description: The order request object that contains a pspReference that represents the order and the matching encrypted order data.
          $ref: '#/components/schemas/EncryptedOrderData'
      required:
      - order
      - merchantAccount
      type: object
    CancelOrderResponse:
      properties:
        pspReference:
          description: A unique reference of the cancellation request.
          type: string
        resultCode:
          description: 'The result of the cancellation request.


            Possible values:


            * **Received**  Indicates the cancellation has successfully been received by Adyen, and will be processed.'
          enum:
          - Received
          type: string
      required:
      - pspReference
      - resultCode
      type: object
    StandalonePaymentCancelResponse:
      properties:
        merchantAccount:
          description: The merchant account that is used to process the payment.
          type: string
        paymentReference:
          description: The [`reference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_reference) of the payment to cancel.
          type: string
        pspReference:
          description: Adyen's 16-character reference associated with the cancel request.
          type: string
        reference:
          description: Your reference for the cancel request.
          type: string
        status:
          description: The status of your request. This will always have the value **received**.
          enum:
          - received
          type: string
      required:
      - status
      - merchantAccount
      - pspReference
      - paymentReference
      type: object
    ApplicationInfo:
      properties:
        adyenLibrary:
          description: Adyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc.
          $ref: '#/components/schemas/CommonField'
        adyenPaymentSource:
          description: Adyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc.
          $ref: '#/components/schemas/CommonField'
        externalPlatform:
          description: Third-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc.
          $ref: '#/components/schemas/ExternalPlatform'
        merchantApplication:
          description: Merchant developed software, such as cashier application, used to interact with the Adyen API.
          $ref: '#/components/schemas/CommonField'
        merchantDevice:
          description: Merchant device information.
          $ref: '#/components/schemas/MerchantDevice'
        shopperInteractionDevice:
          description: Shopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests.
          $ref: '#/components/schemas/ShopperInteractionDevice'
      type: object
    CommonField:
      properties:
        name:
          description: Name of the field. For example, Name of External Platform.
          type: string
        version:
          description: Version of the field. For example, Version of External Platform.
          type: string
      type: object
    MerchantDevice:
      properties:
        os:
          description: Operating system running on the merchant device.
          type: string
        osVersion:
          description: Version of the operating system on the merchant device.
          type: string
        reference:
          description: Merchant device reference.
          type: string
      type: object
    StandalonePaymentCancelRequest:
      properties:
        applicationInfo:
          description: Information about your application. For more details, see [Building Adyen solutions](https://docs.adyen.com/development-resources/building-adyen-solutions).
          $ref: '#/components/schemas/ApplicationInfo'
        merchantAccount:
          description: The merchant account that is used to process the payment.
          type: string
        paymentReference:
          description: The [`reference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__reqParam_reference) of the payment that you want to cancel.
          type: string
        reference:
          description: 'Your reference for the cancel request. Maximum length: 80 characters.'
          type: string
      required:
      - merchantAccount
      - paymentReference
      type: object
    EncryptedOrderData:
      properties:
        orderData:
          description: The encrypted order data.
          type: string
        pspReference:
          description: The `pspReference` that belongs to the order.
          type: string
      required:
      - pspReference
      - orderData
      type: object
    ServiceError:
      properties:
        additionalData:
          x-addedInVersion: '46'
          additionalProperties:
            type: string
          description: Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
          type: object
        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
    ExternalPlatform:
      properties:
        integrator:
          description: External platform integrator.
          type: string
        name:
          description: Name of the field. For example, Name of External Platform.
          type: string
        version:
          description: Version of the field. For example, Version of External Platform.
          type: string
      type: object
    ShopperInteractionDevice:
      properties:
        locale:
          description: Locale on the shopper interaction device.
          type: string
        os:
          description: Operating system running on the shopper interaction device.
          type: string
        osVersion:
          description: Version of the operating system on the shopper interaction device.
          type: string
      type: object
    PaymentCancelRequest:
      properties:
        applicationInfo:
          description: Information about your application. For more details, see [Building Adyen solutions](https://docs.adyen.com/development-resources/building-adyen-solutions).
          $ref: '#/components/schemas/ApplicationInfo'
        merchantAccount:
          description: The merchant account that is used to process the payment.
          type: string
        reference:
          description: 'Your reference for the cancel request. Maximum length: 80 characters.'
          type: string
      required:
      - merchantAccount
      type: object
  examples:
    generic-401:
      summary: Response code 401. Unauthorized.
      value:
        status: 401
        errorCode: '000'
        message: HTTP Status Response - Unauthorized
        errorType: security
    post-cancels-cancel-with-own-reference:
      summary: Cancel a payment using your own reference
      description: Example cancel request with your own reference
      value:
        paymentReference: YOUR_UNIQUE_REFERENCE_FOR_THE_PAYMENT
        reference: YOUR_UNIQUE_REFERENCE_FOR_THE_CANCELLATION
        merchantAccount: YOUR_MERCHANT_ACCOUNT
    generic-400:
      summary: Response code 400. Bad request.
      value:
        status: 400
        errorCode: '702'
        message: 'Unexpected input: ", expected: }'
        errorType: validation
    post-orders-cancel-basic-200:
      summary: Example response for request 'basic'
      value:
        pspReference: '8816178914079738'
        resultCode: Received
    generic-422:
      summary: Response code 422. Unprocessable entity.
      value:
        status: 422
        errorCode: '14_030'
        message: Return URL is missing.
        errorType: validation
        pspReference: '8816118280275544'
    generic-500:
      summary: Response code 500. Internal server error.
      value:
        status: 500
        errorCode: '905'
        message: Payment details are not supported
        errorType: configuration
        pspReference: '8516091485743033'
    post-cancels-cancel-with-own-reference-201:
      summary: Payment cancellation requested
      description: Example response when a payment cancellation was requested
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        paymentReference: YOUR_UNIQUE_REFERENCE_FOR_THE_PAYMENT
        reference: YOUR_UNIQUE_REFERENCE_FOR_THE_CANCELLATION
        pspReference: 993617894906488A
        status: received
    post-orders-cancel-basic:
      summary: Cancel an order
      value:
        order:
          pspReference: '8815517812932012'
          orderData: 823fh892f8f18f4...148f13f9f3f
        merchantAccount: YOUR_MERCHANT_ACCOUNT
    post-payments-paymentPspReference-cancels-cancel-with-psp-reference-201:
      summary: Refund requested
      description: Example response when a refund was requested
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        paymentPspReference: 993617894903480A
        reference: YOUR_UNIQUE_REFERENCE
        pspReference: 993617894906488A
        status: received
    post-payments-paymentPspReference-cancels-cancel-with-psp-reference:
      summary: Cancel payment using a PSP reference
      description: Example cancel request with a PSP reference
      value:
        reference: YOUR_UNIQUE_REFERENCE
        merchantAccount: YOUR_MERCHANT_ACCOUNT
    generic-403:
      summary: Response code 403. Forbidden.
      value:
        status: 403
        errorCode: '901'
        message: Invalid Merchant Account
        errorType: security
        pspReference: 881611827877203B
  parameters:
    Idempotency-Key:
      description: A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).
      example: 37ca9c97-d1d1-4c62-89e8-706891a563ed
      name: Idempotency-Key
      in: header
      schema:
        type: string
  headers:
    Idempotency-Key:
      description: The idempotency key used for processing the request. Present if the key was provided in the request.
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
x-groups:
- Account holders
- Accounts
- Verification