openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Amount 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: Amount
paths:
  /payments/{paymentPspReference}/amountUpdates:
    post:
      tags:
      - Amount
      summary: Adyen Update an Authorised Amount
      description: 'Increases or decreases the authorised payment amount and returns a unique reference for this request. You get the outcome of the request asynchronously, in an [**AUTHORISATION_ADJUSTMENT** webhook](https://docs.adyen.com/development-resources/webhooks/understand-notifications#event-codes).


        You can only update authorised amounts that have not yet been [captured](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/captures).


        The amount you specify in the request is the updated amount, which is larger or smaller than the initial authorised amount.


        For more information, refer to [Authorisation adjustment](https://docs.adyen.com/online-payments/adjust-authorisation#use-cases).'
      operationId: post-payments-paymentPspReference-amountUpdates
      x-sortIndex: 6
      x-methodName: updateAuthorisedAmount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              amount-update:
                $ref: '#/components/examples/post-payments-paymentPspReference-amountUpdates-amount-update'
            schema:
              $ref: '#/components/schemas/PaymentAmountUpdateRequest'
      parameters:
      - description: The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment.
        name: paymentPspReference
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '201':
          content:
            application/json:
              examples:
                amount-update:
                  $ref: '#/components/examples/post-payments-paymentPspReference-amountUpdates-amount-update-201'
              schema:
                $ref: '#/components/schemas/PaymentAmountUpdateResponse'
          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:
    LineItem:
      properties:
        amountExcludingTax:
          description: Item amount excluding the tax, in minor units.
          format: int64
          type: integer
        amountIncludingTax:
          description: Item amount including the tax, in minor units.
          format: int64
          type: integer
        brand:
          x-addedInVersion: '70'
          description: Brand of the item.
          type: string
        color:
          x-addedInVersion: '70'
          description: Color of the item.
          type: string
        description:
          description: Description of the line item.
          type: string
        id:
          description: ID of the line item.
          type: string
        imageUrl:
          description: Link to the picture of the purchased item.
          type: string
        itemCategory:
          description: Item category, used by the payment methods PayPal and Ratepay.
          type: string
        manufacturer:
          x-addedInVersion: '70'
          description: Manufacturer of the item.
          type: string
        productUrl:
          description: Link to the purchased item.
          type: string
        quantity:
          description: Number of items.
          format: int64
          type: integer
        receiverEmail:
          x-addedInVersion: '70'
          description: Email associated with the given product in the basket (usually in electronic gift cards).
          type: string
        size:
          x-addedInVersion: '70'
          description: Size of the item.
          type: string
        sku:
          x-addedInVersion: '70'
          description: Stock keeping unit.
          type: string
        taxAmount:
          description: Tax amount, in minor units.
          format: int64
          type: integer
        taxPercentage:
          description: Tax percentage, in minor units.
          format: int64
          type: integer
        upc:
          x-addedInVersion: '70'
          description: Universal Product Code.
          type: string
      type: object
    PaymentAmountUpdateResponse:
      properties:
        amount:
          description: The updated amount.
          $ref: '#/components/schemas/Amount'
        industryUsage:
          x-addedInVersion: '70'
          description: "The reason for the amount update. Possible values: \n* **delayedCharge** \n* **noShow** \n* **installment**"
          enum:
          - delayedCharge
          - installment
          - noShow
          type: string
        lineItems:
          x-addedInVersion: '71'
          description: 'Price and product information of the refunded items, required for [partial refunds](https://docs.adyen.com/online-payments/refund#refund-a-payment).

            > This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.'
          items:
            $ref: '#/components/schemas/LineItem'
          type: array
        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 update. '
          type: string
        pspReference:
          description: Adyen's 16-character reference associated with the amount update request.
          type: string
        reference:
          description: 'Your reference for the amount update request. Maximum length: 80 characters.'
          type: string
        splits:
          description: An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For details, refer to [Providing split information](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#providing-split-information).
          items:
            $ref: '#/components/schemas/Split'
          type: array
        status:
          description: The status of your request. This will always have the value **received**.
          enum:
          - received
          type: string
      required:
      - status
      - merchantAccount
      - amount
      - reference
      - pspReference
      - paymentPspReference
      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
    SplitAmount:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes). By default, this is the original payment currency.
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The value of the split amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      type: object
    PaymentAmountUpdateRequest:
      properties:
        amount:
          description: The updated amount. The `currency` must match the currency used in authorisation.
          $ref: '#/components/schemas/Amount'
        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'
        industryUsage:
          x-addedInVersion: '70'
          description: "The reason for the amount update. Possible values: \n* **delayedCharge** \n* **noShow** \n* **installment**"
          enum:
          - delayedCharge
          - installment
          - noShow
          type: string
        lineItems:
          x-addedInVersion: '70'
          description: 'Price and product information of the refunded items, required for [partial refunds](https://docs.adyen.com/online-payments/refund#refund-a-payment).

            > This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.'
          items:
            $ref: '#/components/schemas/LineItem'
          type: array
        merchantAccount:
          description: The merchant account that is used to process the payment.
          type: string
        reference:
          description: 'Your reference for the amount update request. Maximum length: 80 characters.'
          type: string
        splits:
          description: An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For details, refer to [Providing split information](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#providing-split-information).
          items:
            $ref: '#/components/schemas/Split'
          type: array
      required:
      - merchantAccount
      - amount
      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
    Amount:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
    Split:
      properties:
        account:
          description: 'The unique identifier of the account to which the split amount is booked. Required if `type` is **MarketPlace** or **BalanceAccount**.


            * [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic): The [`accountCode`](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccount#request-accountCode) of the account to which the split amount is booked.

            * [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms): The [`balanceAccountId`](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/_id_#path-id) of the account to which the split amount is booked.'
          type: string
        amount:
          description: 'The amount of the split item.


            * Required for all split types in the [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic).

            * Required if `type` is **BalanceAccount**, **Commission**, **Default**, or **VAT** in your [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms) integration.'
          $ref: '#/components/schemas/SplitAmount'
        description:
          description: Your description for the split item.
          type: string
        reference:
          description: 'Your unique reference for the split item.


            This is required if `type` is **MarketPlace** ([Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic)) or **BalanceAccount** ([Balance Platform](https://docs.adyen.com/marketplaces-and-platforms)).


            For the other types, we also recommend providing a **unique** reference so you can reconcile the split and the associated payment in the transaction overview and in the reports.'
          type: string
        type:
          description: 'The type of the split item.


            Possible values:


            * [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic): **Commission**, **Default**, **Marketplace**, **PaymentFee**, **VAT**.

            * [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms): **BalanceAccount**, **Commission**, **Default**, **PaymentFee**, **Remainder**, **Surcharge**, **Tip**, **VAT**.'
          enum:
          - AcquiringFees
          - AdyenCommission
          - AdyenFees
          - AdyenMarkup
          - BalanceAccount
          - Commission
          - Default
          - Interchange
          - MarketPlace
          - PaymentFee
          - Remainder
          - SchemeFee
          - Surcharge
          - Tip
          - VAT
          type: string
      required:
      - type
      type: object
  examples:
    generic-401:
      summary: Response code 401. Unauthorized.
      value:
        status: 401
        errorCode: '000'
        message: HTTP Status Response - Unauthorized
        errorType: security
    generic-400:
      summary: Response code 400. Bad request.
      value:
        status: 400
        errorCode: '702'
        message: 'Unexpected input: ", expected: }'
        errorType: validation
    generic-422:
      summary: Response code 422. Unprocessable entity.
      value:
        status: 422
        errorCode: '14_030'
        message: Return URL is missing.
        errorType: validation
        pspReference: '8816118280275544'
    post-payments-paymentPspReference-amountUpdates-amount-update-201:
      summary: Amount update requested
      description: Example response when an amount update was requested
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        paymentPspReference: 993617894903480A
        reference: YOUR_UNIQUE_REFERENCE
        pspReference: 993617894906488A
        status: received
        amount:
          currency: EUR
          value: 2500
    generic-500:
      summary: Response code 500. Internal server error.
      value:
        status: 500
        errorCode: '905'
        message: Payment details are not supported
        errorType: configuration
        pspReference: '8516091485743033'
    generic-403:
      summary: Response code 403. Forbidden.
      value:
        status: 403
        errorCode: '901'
        message: Invalid Merchant Account
        errorType: security
        pspReference: 881611827877203B
    post-payments-paymentPspReference-amountUpdates-amount-update:
      summary: Update the amount of an authorised payment
      description: Example request to update the amount of a payment
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        amount:
          currency: EUR
          value: 2500
        reference: YOUR_UNIQUE_REFERENCE
  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